merge: resolve conflicts with origin/main and keep tui runtime contract boundaries

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>

Author: xgopilot

README.md

@@ -116,6 +116,10 @@ Gateway 转发与自动拉起说明：
 - `/memo`：查看记忆索引
 - `/remember <text>`：保存记忆
 - `/forget <keyword>`：按关键词删除记忆
+- `/skills`：查看当前可用 skills（含当前会话激活标记）
+- `/skill use <id>`：在当前会话启用 skill
+- `/skill off <id>`：在当前会话停用 skill
+- `/skill active`：查看当前会话已激活 skills
 - `& <command>`：在当前工作区执行本地命令
 
 示例输入：
@@ -152,6 +156,7 @@ Gateway 转发与自动拉起说明：
 - [Session 持久化设计](docs/session-persistence-design.md)
 - [Context Compact 说明](docs/context-compact.md)
 - [Tools 与 TUI 集成](docs/tools-and-tui-integration.md)
+- [Skills 设计与使用](docs/skills-system-design.md)
 - [MCP 配置指南](docs/guides/mcp-configuration.md)
 - [更新与升级](docs/guides/update.md)
 

docs/context-compact.md

@@ -25,6 +25,7 @@ context:
   compact:
     manual_strategy: keep_recent
     manual_keep_recent_messages: 10
+    micro_compact_retained_tool_spans: 6
     read_time_max_message_spans: 24
     max_summary_chars: 1200
     micro_compact_disabled: false
@@ -41,6 +42,8 @@ context:
   在 `keep_recent` 模式下保留最近消息数量，并按 tool call 与 tool result 的原子块整体保留。
 - `read_time_max_message_spans`
   控制 `context.Builder` 读时 trim 可保留的 message span 上限；该值越大，普通“继续”续跑时越不容易在未触发 compact 前丢掉较早的文件读取结果。
+- `micro_compact_retained_tool_spans`
+  控制 read-time micro compact 默认保留原始内容的最近可压缩工具块数量；默认值为 `6`，显式配置为更小值时可更积极地回收旧工具结果。
 - `max_summary_chars`
   控制 compact summary 的最大字符数。
 - `micro_compact_disabled`
@@ -61,6 +64,7 @@ context:
 
 新增工具时，micro compact 策略不再由 `context` 层静态白名单维护，而是由 `internal/tools` 中的工具实现声明。
 默认情况下，已注册工具都会参与 micro compact；只有显式声明保留历史结果的工具才会跳过旧结果清理。
+默认 pin 仅对 `filesystem_write_file` 与 `filesystem_edit` 这类文件内容修改工具生效，用于保留 `README`、spec/schema、`go.mod`、`package.json` 等关键产物的最近结果；`.env*` 不参与默认 pin，避免敏感内容在上下文中滞留更久。
 但 micro compact 只有在当前会话已经建立非空 `TaskState` 时才会生效；没有 durable task state 时，context 仅做 trim，不清理旧 tool result。
 
 ## 执行链路

docs/guides/configuration.md

@@ -56,6 +56,7 @@ context:
   compact:
     manual_strategy: keep_recent
     manual_keep_recent_messages: 10
+    micro_compact_retained_tool_spans: 6
     read_time_max_message_spans: 24
     max_summary_chars: 1200
     micro_compact_disabled: false
@@ -81,6 +82,7 @@ context:
 |------|------|
 | `context.compact.manual_strategy` | `/compact` 手动压缩策略，支持 `keep_recent` / `full_replace` |
 | `context.compact.manual_keep_recent_messages` | `keep_recent` 策略下保留的最近消息数 |
+| `context.compact.micro_compact_retained_tool_spans` | read-time micro compact 默认保留原始内容的最近可压缩工具块数量，默认 `6` |
 | `context.compact.read_time_max_message_spans` | context 读时保留的 message span 上限，用于降低“继续”时较早文件读取结果被过早裁掉的风险 |
 | `context.compact.max_summary_chars` | compact summary 最大字符数 |
 | `context.compact.micro_compact_disabled` | 是否关闭默认启用的 micro compact |
@@ -89,6 +91,8 @@ context:
 | `context.auto_compact.reserve_tokens` | 自动阈值推导时预留 token 缓冲（`resolved_threshold = context_window - reserve_tokens`） |
 | `context.auto_compact.fallback_input_token_threshold` | 自动推导失败时使用的保底阈值 |
 
+默认 pin 仅对 `filesystem_write_file` 与 `filesystem_edit` 这类文件修改工具生效，用于保留关键产物文件的最近结果；`.env*` 不参与默认 pin，避免敏感内容在上下文中保留更久。
+
 ### `runtime` 字段
 
 | 字段 | 说明 |

docs/runtime-provider-event-flow.md

@@ -18,6 +18,9 @@
 - `permission_requested`
 - `permission_resolved`
 - `token_usage`
+- `skill_activated`
+- `skill_deactivated`
+- `skill_missing`
 - `compact_start`
 - `compact_applied`
 - `compact_error`

docs/skills-system-design.md

@@ -0,0 +1,116 @@
+# Skills 设计与使用说明
+
+## 1. 目标与定位
+Skills 是 NeoCode 的“能力提示层”，用于给模型提供任务约束、参考资料和工具偏好，不是新的执行层。
+
+主链路保持不变：
+
+`TUI -> Runtime -> Provider / Tool Manager -> Security -> Executor`
+
+Skills 只影响：
+- Context 注入内容
+- 工具暴露顺序（提示优先级）
+
+Skills 不影响：
+- 工具是否真正可执行
+- 权限 ask/deny/allow 决策
+- MCP 注册与权限链路
+
+## 2. 发现机制（Discovery）
+当前本地发现路径：
+- `~/.neocode/skills/`
+
+加载规则：
+- 扫描 root 下的子目录（忽略隐藏目录）
+- 每个 skill 目录要求存在 `SKILL.md`
+- 也支持 root 目录直接放置一个 `SKILL.md`
+- 缺失文件、无效 metadata、空内容会记录为 `LoadIssue`，不阻塞其它 skill 加载
+
+## 3. 加载机制（Loader + Registry）
+核心模块：
+- `internal/skills/loader.go`：本地扫描与解析
+- `internal/skills/registry.go`：内存索引、查询与刷新
+- `internal/skills/filter.go`：按 source/scope/workspace 过滤
+
+关键约束：
+- `SKILL.md` 单文件读取有大小上限（默认 1 MiB）
+- 前置 metadata 和正文解析后统一归一化
+- skill id 去重冲突时 fail-closed（冲突项不进入可用列表）
+
+## 4. skill 文件结构（建议）
+`SKILL.md` 支持 frontmatter + 正文 section：
+
+```md
+---
+id: go-review
+name: Go Review
+description: Go 代码审查助手
+version: v1
+scope: session
+source: local
+tool_hints:
+  - filesystem_read_file
+  - filesystem_grep
+---
+
+## Instruction
+优先做静态阅读，再给出可执行修改建议。
+
+## References
+- [代码规范](./guides/go-style.md)
+
+## Examples
+- 先总结问题，再给补丁
+
+## ToolHints
+- filesystem_read_file
+- filesystem_grep
+```
+
+## 5. 激活与会话模型
+Runtime 提供会话级接口：
+- `ActivateSessionSkill(session_id, skill_id)`
+- `DeactivateSessionSkill(session_id, skill_id)`
+- `ListSessionSkills(session_id)`
+- `ListAvailableSkills(session_id)`
+
+TUI 入口：
+- `/skills`
+- `/skill use <id>`
+- `/skill off <id>`
+- `/skill active`
+
+说明：
+- `use/off/active` 需要当前有 active session
+- session 重载后会恢复 `activated_skills` 状态
+- skill 在 registry 中缺失时，会标记为 missing 并发出事件
+
+## 6. 模型如何使用 skill
+Runtime 在每轮 context 构建时把激活 skills 注入 `Skills` section，内容包含：
+- instruction
+- tool_hints（裁剪）
+- references（裁剪）
+- examples（裁剪）
+
+模型预期行为：
+- 把 skill 当成策略与工作流提示
+- 只调用当前真实暴露的工具 schema
+- 通过正常工具调用链路执行，不跳过权限层
+
+## 7. Tools / Security / MCP 边界
+Skills 与安全边界的约束：
+- skill 不能注入未注册工具
+- skill 不能变成权限 allowlist
+- skill 不能绕过 `PermissionEngine` 的 ask/deny/allow
+- MCP 工具仍经过统一 registry + exposure filter + permission 检查
+
+当前实现中，`tool_hints` 仅用于对已暴露工具做排序优先级调整，不会新增工具，也不会改变权限决策。
+
+## 8. 可观测事件
+Runtime 会发出以下 skills 事件（供 TUI/日志调试）：
+- `skill_activated`
+- `skill_deactivated`
+- `skill_missing`
+
+## 9. 兼容与扩展
+当前 focus 是本地 skills；后续如需引入 remote source / marketplace，可在 `Loader` 与 `Registry` 层扩展，不需要改动 runtime 主执行链路。

docs/tools-and-tui-integration.md

@@ -30,6 +30,12 @@
 - TUI 的 `/memo`、`/remember`、`/forget` 等 Slash Command 不再直接依赖 memo service，而是通过 `Runtime.ExecuteSystemTool` 统一入口触发系统工具执行，保证 UI 与 memo 逻辑解耦。
 - TUI 不会展示后台自动提取的中间状态。
 
+## Skills 能力集成
+- Skills 由 `internal/skills` 统一发现、加载和注册；TUI 不直接读取 `SKILL.md` 文件。
+- TUI 通过 runtime 接口管理会话激活状态：`/skills`、`/skill use <id>`、`/skill off <id>`、`/skill active`。
+- Skills 只影响提示注入与工具排序优先级，不改变工具执行入口；真实调用仍走 `Runtime -> Tool Manager -> Security -> Executor`。
+- Skills 不提供权限豁免；命中 ask/deny 规则时行为与未启用 skill 保持一致。
+
 ## TUI 集成方式
 - 本地配置操作统一通过 Slash Command 完成，例如 Base URL、API Key 和模型选择
 - runtime 事件以内联形式渲染到 transcript 中，而不是单独拆出控制台面板

go.mod

@@ -11,7 +11,7 @@ require (
 	github.com/charmbracelet/glamour v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
 	github.com/creativeprojects/go-selfupdate v1.5.2
-	github.com/openai/openai-go/v3 v3.30.0
+	github.com/openai/openai-go/v3 v3.32.0
 	github.com/prometheus/client_golang v1.23.2
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0

go.sum

@@ -184,6 +184,8 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/openai/openai-go/v3 v3.30.0 h1:T8VkhqAm6BuvxwpVG+Aw+H4TcYIsbj9nqytjpWcE/aU=
 github.com/openai/openai-go/v3 v3.30.0/go.mod h1:cdufnVK14cWcT9qA1rRtrXx4FTRsgbDPW7Ia7SS5cZo=
+github.com/openai/openai-go/v3 v3.32.0 h1:aHp/3wkX1W6jB8zTtf9xV0aK0qPFSVDqS7AHmlJ4hXs=
+github.com/openai/openai-go/v3 v3.32.0/go.mod h1:cdufnVK14cWcT9qA1rRtrXx4FTRsgbDPW7Ia7SS5cZo=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

internal/app/bootstrap.go

@@ -26,6 +26,7 @@ import (
 	"neo-code/internal/tools/filesystem"
 	"neo-code/internal/tools/mcp"
 	memotool "neo-code/internal/tools/memo"
+	"neo-code/internal/tools/spawnsubagent"
 	"neo-code/internal/tools/todo"
 	"neo-code/internal/tools/webfetch"
 	"neo-code/internal/tui"
@@ -349,6 +350,7 @@ func buildToolRegistry(cfg config.Config) (*tools.Registry, func() error, error)
 		SupportedContentTypes: cfg.Tools.WebFetch.SupportedContentTypes,
 	}))
 	toolRegistry.Register(todo.New())
+	toolRegistry.Register(spawnsubagent.New())
 	mcpRegistry, err := buildMCPRegistry(cfg)
 	if err != nil {
 		return nil, nil, err

internal/app/bootstrap_test.go

@@ -181,6 +181,43 @@ func TestBuildToolRegistryUsesWebFetchConfig(t *testing.T) {
 	}
 }
 
+func TestBuildToolRegistryRegistersSpawnSubAgent(t *testing.T) {
+	t.Parallel()
+
+	cfg := config.StaticDefaults().Clone()
+	cfg.Workdir = t.TempDir()
+
+	registry, cleanup, err := buildToolRegistry(cfg)
+	if err != nil {
+		t.Fatalf("buildToolRegistry() error = %v", err)
+	}
+	if cleanup != nil {
+		defer cleanup()
+	}
+
+	tool, err := registry.Get(tools.ToolNameSpawnSubAgent)
+	if err != nil {
+		t.Fatalf("registry.Get(spawn_subagent) error = %v", err)
+	}
+	if tool.Name() != tools.ToolNameSpawnSubAgent {
+		t.Fatalf("tool.Name() = %q, want %q", tool.Name(), tools.ToolNameSpawnSubAgent)
+	}
+	specs, err := registry.ListAvailableSpecs(context.Background(), tools.SpecListInput{})
+	if err != nil {
+		t.Fatalf("ListAvailableSpecs() error = %v", err)
+	}
+	found := false
+	for _, spec := range specs {
+		if spec.Name == tools.ToolNameSpawnSubAgent {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("expected %q in available specs, got %+v", tools.ToolNameSpawnSubAgent, specs)
+	}
+}
+
 func TestBuildMCPRegistryFromConfig(t *testing.T) {
 	stubClient := &stubMCPServerClient{
 		tools: []mcp.ToolDescriptor{
@@ -1672,6 +1709,13 @@ func (s *stubRemoteRuntimeForBootstrap) ListSessionSkills(context.Context, strin
 	return nil, nil
 }
 
+func (s *stubRemoteRuntimeForBootstrap) ListAvailableSkills(
+	context.Context,
+	string,
+) ([]services.AvailableSkillState, error) {
+	return nil, nil
+}
+
 func (s *stubRemoteRuntimeForBootstrap) Close() error {
 	s.closed = true
 	return nil