Merge pull request #24 from Yumiue/codex/github-pages-vitepress-site

fix(ci): scope node24 override and simplify pages workflow

Author: wynxing

.github/workflows/pages.yml

@@ -3,7 +3,7 @@ name: Deploy VitePress Site
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
   workflow_dispatch:
 
 permissions:
@@ -17,16 +17,20 @@ concurrency:
 
 jobs:
   build:
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    defaults:
+      run:
+        working-directory: www
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
+          version: 10.32.0
           run_install: false
 
       - name: Setup Node
@@ -40,11 +44,9 @@ jobs:
         uses: actions/configure-pages@v4
 
       - name: Install dependencies
-        working-directory: www
         run: pnpm install --frozen-lockfile
 
       - name: Build with VitePress
-        working-directory: www
         run: pnpm docs:build
 
       - name: Upload artifact

.skills/issue-rfc-architecture/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "issue-rfc-architecture"
+description: "用于创建架构类 Issue（RFC 风格）。当用户需要明确模块边界、核心设计和落地路线时使用。"
+---
+
+# Issue RFC Architecture
+
+适用于“架构类”议题，强调边界、职责和关键设计选择。
+
+## 使用步骤
+
+1. 先确认目标问题和影响模块。
+2. 运行命令创建 issue：
+
+```bash
+./scripts/create_issue.sh --type architecture --title "<架构标题>"
+```
+
+3. 如需自定义正文，先准备 markdown 文件，再执行：
+
+```bash
+./scripts/create_issue.sh --type architecture --title "<架构标题>" --body-file <path>
+```
+
+## 质量要求
+
+- 正文必须包含：目标问题、现状与边界、核心设计、落地清单、验收标准、风险与回滚。
+- 设计必须说明“为什么是这个方案”，并给出边界分工。
+- 验收项应覆盖正常路径、异常路径、恢复路径。

.skills/issue-rfc-implementation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "issue-rfc-implementation"
+description: "用于创建实现类 Issue（RFC 执行单风格）。当用户要把已确认提案/架构落地成可执行任务时使用。"
+---
+
+# Issue RFC Implementation
+
+适用于“实现类”议题，强调关联上游 RFC、改动范围和验证闭环。
+
+## 使用步骤
+
+1. 先确认已关联的提案/架构 issue。
+2. 运行命令创建 issue：
+
+```bash
+./scripts/create_issue.sh --type implementation --title "<实现标题>"
+```
+
+3. 如需自定义正文，先准备 markdown 文件，再执行：
+
+```bash
+./scripts/create_issue.sh --type implementation --title "<实现标题>" --body-file <path>
+```
+
+## 质量要求
+
+- 正文必须包含：关联 RFC、目标问题、实现设计、任务清单、测试验证、风险与回滚。
+- 任务清单要可执行且可追踪，不接受抽象口号。
+- 测试清单至少覆盖正常路径、边界条件、异常分支。

.skills/issue-rfc-proposal/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "issue-rfc-proposal"
+description: "用于创建提案类 Issue（RFC 风格）。当用户希望在本仓库发起‘目标问题 -> 设计 -> 落地清单’的提案讨论时使用。"
+---
+
+# Issue RFC Proposal
+
+适用于“提案类”议题，要求输出遵循：目标问题（Why）-> 设计方案（How）-> 落地清单（What）。
+
+## 使用步骤
+
+1. 先让用户明确提案标题与核心痛点。
+2. 运行命令创建 issue：
+
+```bash
+./scripts/create_issue.sh --type proposal --title "<提案标题>"
+```
+
+3. 如需自定义正文，先准备 markdown 文件，再执行：
+
+```bash
+./scripts/create_issue.sh --type proposal --title "<提案标题>" --body-file <path>
+```
+
+## 质量要求
+
+- 正文必须包含：目标问题、设计方案、落地清单、验收标准、风险与回滚。
+- 非目标必须明确，避免提案发散。
+- 验收标准必须可验证，避免空泛表述。

AGENTS.md

@@ -3,16 +3,17 @@
 本文件是本仓库的 AI 协作规则。任何 AI 在本项目中进行改写、续写、重构、修复、补测试或补文档时，都应优先遵守本文件。
 
 ## 1. 任务目标
-- 本仓库的目标是实现 `NeoCode Coding Agent MVP`。
-- 当前主链路必须始终围绕以下闭环保持可用：
-  `用户输入 -> Agent 推理 -> 调用工具 -> 获取结果 -> 继续推理 -> UI 展示`
+- 本仓库的目标是实现 `NeoCode Coding Agent`。
+- 系统已完成控制面与数据面解耦，当前主链路必须始终围绕以下闭环保持可用：
+  `用户输入(TUI) -> 网关中继(Gateway) -> Agent推理(Runtime) -> 调用工具(Tools) -> 结果回传 -> UI展示`
 - 做改动时，优先保证主链路可运行、模块边界清晰、实现可验证。
 
 ## 2. 最高优先级规则
 - 不要为了“可能兼容旧版本”破坏当前架构；若新设计已确定，优先直接切换到新实现。
 - 不允许过度设计、过度包装
 - 项目中可能存在语义不清的地方，必须要谨慎分析
-- 不要跨层直连；新功能默认沿 `TUI -> Runtime -> Provider / Tool Manager` 主链路设计。
+- **强制编码准则 (防乱码)**：所有文件的读取、修改、重写操作必须强制使用标准 **UTF-8 (无 BOM)** 编码。严禁使用破坏多字节字符的正则替换；严禁在输出中文注释时出现截断或混入 GBK 等其他编码。发现乱码先修编码再修逻辑。
+- 不要跨层直连；新功能默认沿 `TUI -> Gateway -> Runtime -> Provider / Tool Manager` 主链路设计。
 - 不要把模型厂商差异泄漏到 `runtime`、`tui` 或上层调用方。
 - 不要在 `runtime` 或 `tui` 里直接写工具执行逻辑；所有可被模型调用的能力必须进入 `internal/tools`。
 - 不要把会话状态、消息历史、工具调用记录散落到 UI；这些状态优先由 `runtime` 管理。
@@ -23,13 +24,14 @@
 
 ### 3.1 关键目录
 - `cmd/neocode`：CLI 入口。
-- `internal/app`：应用装配与 bootstrap，负责连接 config、provider、tools、runtime、tui。
-- `internal/config`：配置模型、YAML 加载、环境变量管理、配置校验和并发安全访问。
-- `internal/provider`：provider 抽象、领域模型和各厂商适配器。
-- `internal/runtime`：ReAct 主循环、事件流、Prompt 编排、token 累积与自动压缩触发。
-- `internal/session`：会话领域模型、存储抽象与 JSON 持久化实现。
+- `internal/app`：应用装配与 bootstrap，负责组装 Gateway、Runtime、TUI 等组件。
+- `internal/config`：配置模型、YAML 加载、环境变量管理及校验。
+- `internal/tui`：纯 UI 渲染层、Bubble Tea 状态机。仅负责消费事件并展示，不存业务状态。
+- `internal/gateway`：协议路由中枢。负责 IPC/网络监听、JSON-RPC 归一化、ACL 鉴权和流式事件中继。
+- `internal/runtime`：业务大脑。负责 ReAct 循环、事件流、Prompt 编排、Token 累积与压缩触发。不接触 UI。
+- `internal/provider`：各厂商模型适配器、请求组装与流式响应解析。
+- `internal/session`：会话领域模型、存储抽象与 JSON/SQLite 持久化。
 - `internal/tools`：工具契约、注册表、参数校验和具体工具实现。
-- `internal/tui`：Bubble Tea 状态机、渲染层、Slash Command 和事件桥接。
 - `docs`：架构、配置、事件流、会话持久化等说明文档。
 
 ### 3.2 模块职责

Makefile

@@ -0,0 +1,4 @@
+.PHONY: install-skills
+
+install-skills:
+	@./scripts/install_skills.sh

README.md

@@ -113,18 +113,11 @@ $env:QINIU_API_KEY = "your_key_here"
 go run ./cmd/neocode --workdir /path/to/workspace
 ```
 
-运行模式切换（默认 `local`）：
+Gateway 转发与自动拉起说明：
 
-```bash
-go run ./cmd/neocode --runtime-mode local
-go run ./cmd/neocode --runtime-mode gateway
-```
-
-说明：
-
-- `--runtime-mode` 仅影响当前进程，不会回写 `config.yaml`
-- `gateway` 模式会通过本地 Gateway（优先 IPC）转发 runtime 请求与事件流
-- 若 Gateway 不可达或握手失败会直接报错退出（Fail Fast），不会自动回退到 `local`
+- `neocode` 默认通过本地 Gateway（优先 IPC）转发 runtime 请求与事件流
+- 启动时会先探测本地网关；若未运行会自动后台拉起并等待就绪（无感）
+- 若自动拉起后仍不可达或握手失败，会直接报错退出（Fail Fast）
 
 ### 4) 首次使用与常用命令
 - `/help`：查看命令帮助
@@ -136,6 +129,10 @@ go run ./cmd/neocode --runtime-mode gateway
 - `/memo`：查看记忆索引
 - `/remember <text>`：保存记忆
 - `/forget <keyword>`：按关键词删除记忆
+- `/skills`：查看当前可用 skills（含当前会话激活标记）
+- `/skill use <id>`：在当前会话启用 skill
+- `/skill off <id>`：在当前会话停用 skill
+- `/skill active`：查看当前会话已激活 skills
 - `& <command>`：在当前工作区执行本地命令
 
 示例输入：
@@ -153,7 +150,7 @@ go run ./cmd/neocode --runtime-mode gateway
 
 - API Key 通过环境变量注入，不写入 `config.yaml`
 - `--workdir` 只影响当前运行，不会回写到配置文件
-- `--runtime-mode` 默认 `local`，用于灰度切换到 `gateway` 模式
+- TUI 默认通过 Gateway 连接 runtime，启动时会自动探测并在必要时后台拉起网关
 
 详细配置请参考：[docs/guides/configuration.md](docs/guides/configuration.md)
 
@@ -172,6 +169,7 @@ go run ./cmd/neocode --runtime-mode 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)
 
@@ -194,6 +192,47 @@ go run ./cmd/neocode --runtime-mode gateway
 - 不提交明文密钥、个人配置或会话数据
 - 不提交无关改动与临时文件
 
+## 在仓库内直接创建 Issue（Skills + 自动化）
+
+仓库提供三类同前缀 skill（位于 `.skills/`）：
+
+- `issue-rfc-proposal`（提案类，RFC 风格）
+- `issue-rfc-architecture`（架构类，RFC 风格）
+- `issue-rfc-implementation`（实现类，执行单风格）
+
+先安装 skills 到仓库内常见 AI Coding 工具目录：
+
+```bash
+make install-skills
+```
+
+默认会安装到以下目录（均在仓库内）：
+
+- `.codex/skills`
+- `.claude/skills`
+- `.cursor/skills`
+- `.windsurf/skills`
+
+如需自定义安装目标，可设置环境变量 `SKILL_INSTALL_TARGETS`（冒号分隔目录）：
+
+```bash
+SKILL_INSTALL_TARGETS=".codex/skills:.claude/skills" make install-skills
+```
+
+Skill 内部调用脚本 `scripts/create_issue.sh` 创建 issue。你也可以直接执行脚本：
+
+```bash
+./scripts/create_issue.sh --type proposal --title "统一会话中断恢复语义"
+./scripts/create_issue.sh --type architecture --title "Runtime 与 Session 账本边界梳理"
+./scripts/create_issue.sh --type implementation --title "补齐流式中断持久化" --labels "bug,priority-high"
+```
+
+脚本可选参数：
+
+- `--repo <owner/repo>`：指定目标仓库（默认自动识别当前仓库）
+- `--body-file <path>`：自定义 issue 正文文件（不传则使用内置模板）
+- `--labels <a,b,c>`：追加标签（逗号分隔）
+
 ## 网关运维与安全（GW-06）
 
 - 静默认证（Silent Auth）：

docs/guides/configuration.md

@@ -246,22 +246,20 @@ $env:GEMINI_API_KEY = "AI..."
 
 ## CLI 运行参数覆盖
 
-工作目录与运行模式都不写入 `config.yaml`，只通过启动参数覆盖：
+工作目录不写入 `config.yaml`，只通过启动参数覆盖：
 
 ```bash
 go run ./cmd/neocode --workdir /path/to/workspace
-go run ./cmd/neocode --runtime-mode local
-go run ./cmd/neocode --runtime-mode gateway
 ```
 
 说明：
 
 - `--workdir` 只影响本次进程
 - 不会回写到 `config.yaml`
 - 工具根目录与 session 隔离都会使用该工作区
-- `--runtime-mode` 默认为 `local`，可切换为 `gateway`
-- `gateway` 模式会通过本地 Gateway（优先 IPC）转发 runtime 请求
-- 连接或握手失败会直接退出（Fail Fast），不会自动回退到 `local`
+- TUI 默认通过本地 Gateway（优先 IPC）转发 runtime 请求
+- 启动时会先探测本地网关；若未运行会自动后台拉起并等待就绪
+- 若自动拉起后仍连接或握手失败会直接退出（Fail Fast）
 
 ## 常见错误
 

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`