Merge branch 'main' into main

Author: phantom5099

README.md

@@ -2,16 +2,14 @@
 
 > 基于 Go + Bubble Tea 的本地 Coding Agent
 
-## NeoCode 是什么
-
+## NeoCode 是什么？
 NeoCode 是一个在终端中运行的 AI 编码助手，采用 ReAct（Reason-Act-Observe）循环模式，围绕以下主链路工作：
 
 `用户输入 -> Agent 推理 -> 调用工具 -> 获取结果 -> 继续推理 -> UI 展示`
 
 它适合希望在本地工作流中完成代码理解、修改、调试与自动化操作的开发者。
 
-## 有什么能力
-
+## 有什么能力？
 - 终端原生 TUI 交互体验（Bubble Tea）
 - Agent 可调用内置工具完成文件与命令相关任务
 - 支持 Provider/Model 切换（内建 `openai`、`gemini`、`openll`、`qiniu`）
@@ -23,26 +21,21 @@ NeoCode 是一个在终端中运行的 AI 编码助手，采用 ReAct（Reason-A
 ## 怎么用（快速开始）
 
 ### 1) 环境要求
-
 - Go `1.25+`
 - 可用的 API Key（如 OpenAI、Gemini、OpenLL、Qiniu）
 
 ### 2) 一键安装
-
 macOS / Linux：
-
 ```bash
 curl -fsSL https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.sh | bash
 ```
 
 Windows PowerShell：
-
 ```powershell
 irm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.ps1 | iex
 ```
 
 ### 3) 从源码运行
-
 ```bash
 git clone https://github.com/1024XEngineer/neo-code.git
 cd neo-code
@@ -70,8 +63,9 @@ go run ./cmd/neocode gateway --http-listen 127.0.0.1:8080
 安全限制：为防止跨站攻击，网关网络面默认开启严格的 Origin 校验。当前仅允许
 `http://localhost`、`http://127.0.0.1`、`http://[::1]` 以及 `app://` 前缀来源连入；
 非允许来源的跨域调用会被拦截并返回 `403`。
+
 注：上述白名单机制仅针对携带 `Origin` 头的浏览器跨站请求生效。若请求不携带 `Origin` 头
-（例如 `cURL`、Postman 或本地后端脚本直连），网关默认放行。
+（例如 `curl`、Postman 或本地后端脚本直连），网关默认放行。
 
 URL Scheme 派发骨架命令（EPIC-GW-02A）：
 
@@ -93,7 +87,6 @@ export QINIU_API_KEY="your_key_here"
 ```
 
 Windows PowerShell：
-
 ```powershell
 $env:OPENAI_API_KEY = "your_key_here"
 $env:GEMINI_API_KEY = "your_key_here"
@@ -121,7 +114,6 @@ go run ./cmd/neocode --runtime-mode gateway
 - 若 Gateway 不可达或握手失败会直接报错退出（Fail Fast），不会自动回退到 `local`
 
 ### 4) 首次使用与常用命令
-
 - `/help`：查看命令帮助
 - `/provider`：打开 provider 选择器
 - `/model`：打开 model 选择器
@@ -134,7 +126,6 @@ go run ./cmd/neocode --runtime-mode gateway
 - `& <command>`：在当前工作区执行本地命令
 
 示例输入：
-
 ```text
 请先阅读当前项目目录结构并给出模块职责摘要
 帮我在 internal/runtime 下定位与 tool result 回灌相关逻辑
@@ -153,6 +144,13 @@ go run ./cmd/neocode --runtime-mode gateway
 
 详细配置请参考：[docs/guides/configuration.md](docs/guides/configuration.md)
 
+## 内部结构补充
+
+- `internal/context`：负责主会话 system prompt 的 section 组装、动态上下文注入与消息裁剪。
+- `internal/runtime`：负责 ReAct 主循环、tool 调用编排、compact 触发与 reminder 注入时机。
+- `internal/subagent`：负责子代理角色策略、执行约束与输出契约。
+- `internal/promptasset`：负责受版本管理的静态 prompt 模板资产，使用 `go:embed` 编译进程序，供 `context`、`runtime`、`subagent` 读取。
+
 ## 文档导航
 
 - [配置指南](docs/guides/configuration.md)
@@ -172,17 +170,14 @@ go run ./cmd/neocode --runtime-mode gateway
 2. Fork 仓库并创建功能分支。
 3. 完成开发并确保改动聚焦、边界清晰。
 4. 本地自检：
-
    ```bash
    gofmt -w ./cmd ./internal
    go test ./...
    go build ./...
    ```
-
 5. 提交 PR 到主仓库并说明变更目的、影响范围和验证方式。
 
 提交前请确认：
-
 - 不提交明文密钥、个人配置或会话数据
 - 不提交无关改动与临时文件
 
@@ -205,21 +200,22 @@ go run ./cmd/neocode --runtime-mode gateway
   - `http_max_stream_connections=128`
   - `ipc_read/write_sec=30/30`
   - `http_read/write/shutdown_sec=15/15/2`
-- 详细设计文档：[`docs/gateway-detailed-design.md`](docs/gateway-detailed-design.md)
+
+详细设计文档：[`docs/gateway-detailed-design.md`](docs/gateway-detailed-design.md)
 
 ### Gateway JSON-RPC 方法清单（当前实现）
 
 - `gateway.authenticate`：连接级鉴权握手
 - `gateway.ping`：探活
 - `gateway.bindStream`：会话流绑定
-- `gateway.run`：发起一次运行
+- `gateway.run`：发起一次运行（Accepted-ACK，异步执行）
 - `gateway.compact`：触发会话压缩
-- `gateway.cancel`：取消当前活跃运行
+- `gateway.cancel`：按 `run_id` 精确取消目标运行（`run_id` 必填）
 - `gateway.listSessions`：查询会话摘要列表
 - `gateway.loadSession`：加载单个会话详情
 - `gateway.resolvePermission`：提交权限审批结果
 - `wake.openUrl`：处理 `neocode://` 唤醒请求
-- `gateway.event`：网关推送的通知事件（notification）
+- `gateway.event`：网关推送通知事件（notification）
 
 ## License
 

docs/config-management-detail-design.md

@@ -69,6 +69,7 @@ custom provider 来自：
 ```
 
 当前只接受明确受支持的字段；未知字段会直接报错，不做“旧格式自动迁移”。
+`provider.yaml` 只支持平铺字段：`name/driver/base_url/api_key_env/model_source/chat_endpoint_path/discovery_endpoint_path/models`。
 
 ## 加载流程
 

docs/context-compact.md

@@ -14,6 +14,7 @@
 - `internal/context/compact` 支持 `manual`、`auto` 与 `reactive` 三种 mode。
 - 用户通过 `/compact` 对当前会话执行一次上下文压缩。
 - compact 前会先写入完整 transcript，随后生成并校验新的 durable `TaskState` 与 display summary，再回写会话消息。
+- compact 的 system prompt 静态说明模板由 `internal/promptasset` 通过 `go:embed` 提供，但 compact user prompt 的元数据块、消息边界和 transcript 渲染仍由代码拼装。
 
 ## 配置
 
@@ -112,6 +113,8 @@ compact generator 必须只返回一个 JSON 对象，顶层固定包含：
 - `task_state` 只允许包含固定字段，不允许混入模型自定义键。
 - `display_summary` 仍然必须使用 `[compact_summary]` 协议，供人类阅读和后续轮次参考。
 
+上述 JSON 契约与 `[compact_summary]` 格式模板仍由代码注入到 compact system prompt 中，避免在模板文件里复制一份会随实现演进的协议定义。
+
 `display_summary` 必须以如下结构返回：
 
 ```text