@tencent-ai/agent-sdk 0.3.155 → 0.3.158

package/cli/dist/web-ui/assets/workbox-window.prod.es5-BBnX5xw4.js

@@ -0,0 +1,2 @@
+try{self["workbox:window:7.4.0"]&&_()}catch{}function b(t,r){return new Promise((function(n){var u=new MessageChannel;u.port1.onmessage=function(s){n(s.data)},t.postMessage(r,[u.port2])}))}function P(t,r){(r==null||r>t.length)&&(r=t.length);for(var n=0,u=Array(r);n<r;n++)u[n]=t[n];return u}function j(t,r,n){return r&&(function(u,s){for(var c=0;c<s.length;c++){var o=s[c];o.enumerable=o.enumerable||!1,o.configurable=!0,"value"in o&&(o.writable=!0),Object.defineProperty(u,W(o.key),o)}})(t.prototype,r),Object.defineProperty(t,"prototype",{writable:!1}),t}function S(t,r){var n=typeof Symbol<"u"&&t[Symbol.iterator]||t["@@iterator"];if(n)return(n=n.call(t)).next.bind(n);if(Array.isArray(t)||(n=(function(s,c){if(s){if(typeof s=="string")return P(s,c);var o={}.toString.call(s).slice(8,-1);return o==="Object"&&s.constructor&&(o=s.constructor.name),o==="Map"||o==="Set"?Array.from(s):o==="Arguments"||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(o)?P(s,c):void 0}})(t))||r){n&&(t=n);var u=0;return function(){return u>=t.length?{done:!0}:{done:!1,value:t[u++]}}}throw new TypeError(`Invalid attempt to iterate non-iterable instance.
+In order to be iterable, non-array objects must have a [Symbol.iterator]() method.`)}function w(t,r){return w=Object.setPrototypeOf?Object.setPrototypeOf.bind():function(n,u){return n.__proto__=u,n},w(t,r)}function W(t){var r=(function(n,u){if(typeof n!="object"||!n)return n;var s=n[Symbol.toPrimitive];if(s!==void 0){var c=s.call(n,u);if(typeof c!="object")return c;throw new TypeError("@@toPrimitive must return a primitive value.")}return String(n)})(t,"string");return typeof r=="symbol"?r:r+""}try{self["workbox:core:7.4.0"]&&_()}catch{}var m=function(){var t=this;this.promise=new Promise((function(r,n){t.resolve=r,t.reject=n}))};function y(t,r){var n=location.href;return new URL(t,n).href===new URL(r,n).href}var d=function(t,r){this.type=t,Object.assign(this,r)};function l(t,r,n){return t&&t.then||(t=Promise.resolve(t)),r?t.then(r):t}function k(){}var L={type:"SKIP_WAITING"};function E(t,r){return t&&t.then?t.then(k):Promise.resolve()}var O=(function(t){function r(c,o){var e,i;return o===void 0&&(o={}),(e=t.call(this)||this).nn={},e.tn=0,e.rn=new m,e.en=new m,e.on=new m,e.un=0,e.an=new Set,e.cn=function(){var f=e.fn,a=f.installing;e.tn>0||!y(a.scriptURL,e.sn.toString())||performance.now()>e.un+6e4?(e.vn=a,f.removeEventListener("updatefound",e.cn)):(e.hn=a,e.an.add(a),e.rn.resolve(a)),++e.tn,a.addEventListener("statechange",e.ln)},e.ln=function(f){var a=e.fn,v=f.target,h=v.state,p=v===e.vn,g={sw:v,isExternal:p,originalEvent:f};!p&&e.mn&&(g.isUpdate=!0),e.dispatchEvent(new d(h,g)),h==="installed"?e.wn=self.setTimeout((function(){h==="installed"&&a.waiting===v&&e.dispatchEvent(new d("waiting",g))}),200):h==="activating"&&(clearTimeout(e.wn),p||e.en.resolve(v))},e.yn=function(f){var a=e.hn,v=a!==navigator.serviceWorker.controller;e.dispatchEvent(new d("controlling",{isExternal:v,originalEvent:f,sw:a,isUpdate:e.mn})),v||e.on.resolve(a)},e.gn=(i=function(f){var a=f.data,v=f.ports,h=f.source;return l(e.getSW(),(function(){e.an.has(h)&&e.dispatchEvent(new d("message",{data:a,originalEvent:f,ports:v,sw:h}))}))},function(){for(var f=[],a=0;a<arguments.length;a++)f[a]=arguments[a];try{return Promise.resolve(i.apply(this,f))}catch(v){return Promise.reject(v)}}),e.sn=c,e.nn=o,navigator.serviceWorker.addEventListener("message",e.gn),e}var n,u;u=t,(n=r).prototype=Object.create(u.prototype),n.prototype.constructor=n,w(n,u);var s=r.prototype;return s.register=function(c){var o=(c===void 0?{}:c).immediate,e=o!==void 0&&o;try{var i=this;return l((function(f,a){var v=f();return v&&v.then?v.then(a):a(v)})((function(){if(!e&&document.readyState!=="complete")return E(new Promise((function(f){return window.addEventListener("load",f)})))}),(function(){return i.mn=!!navigator.serviceWorker.controller,i.dn=i.pn(),l(i.bn(),(function(f){i.fn=f,i.dn&&(i.hn=i.dn,i.en.resolve(i.dn),i.on.resolve(i.dn),i.dn.addEventListener("statechange",i.ln,{once:!0}));var a=i.fn.waiting;return a&&y(a.scriptURL,i.sn.toString())&&(i.hn=a,Promise.resolve().then((function(){i.dispatchEvent(new d("waiting",{sw:a,wasWaitingBeforeRegister:!0}))})).then((function(){}))),i.hn&&(i.rn.resolve(i.hn),i.an.add(i.hn)),i.fn.addEventListener("updatefound",i.cn),navigator.serviceWorker.addEventListener("controllerchange",i.yn),i.fn}))})))}catch(f){return Promise.reject(f)}},s.update=function(){try{return this.fn?l(E(this.fn.update())):l()}catch(c){return Promise.reject(c)}},s.getSW=function(){return this.hn!==void 0?Promise.resolve(this.hn):this.rn.promise},s.messageSW=function(c){try{return l(this.getSW(),(function(o){return b(o,c)}))}catch(o){return Promise.reject(o)}},s.messageSkipWaiting=function(){this.fn&&this.fn.waiting&&b(this.fn.waiting,L)},s.pn=function(){var c=navigator.serviceWorker.controller;return c&&y(c.scriptURL,this.sn.toString())?c:void 0},s.bn=function(){try{var c=this;return l((function(o,e){try{var i=o()}catch(f){return e(f)}return i&&i.then?i.then(void 0,e):i})((function(){return l(navigator.serviceWorker.register(c.sn,c.nn),(function(o){return c.un=performance.now(),o}))}),(function(o){throw o})))}catch(o){return Promise.reject(o)}},j(r,[{key:"active",get:function(){return this.en.promise}},{key:"controlling",get:function(){return this.on.promise}}])})((function(){function t(){this.Pn=new Map}var r=t.prototype;return r.addEventListener=function(n,u){this.jn(n).add(u)},r.removeEventListener=function(n,u){this.jn(n).delete(u)},r.dispatchEvent=function(n){n.target=this;for(var u,s=S(this.jn(n.type));!(u=s()).done;)(0,u.value)(n)},r.jn=function(n){return this.Pn.has(n)||this.Pn.set(n,new Set),this.Pn.get(n)},t})());export{O as Workbox,d as WorkboxEvent,b as messageSW};

package/cli/dist/web-ui/docs/cn/cli/codebuddy-dir.md

@@ -0,0 +1,309 @@
+# .codebuddy 目录结构说明
+
+> 深入了解 CodeBuddy Code 的配置目录 `~/.codebuddy` 和项目级 `.codebuddy` 的文件与子目录。
+
+CodeBuddy Code 使用两种配置目录：
+
+- **全局目录** `~/.codebuddy/`：存储用户级配置、历史数据、运行时数据等，影响所有项目
+- **项目目录** `.codebuddy/`（位于项目根目录）：存储项目级配置、规则、技能、命令等，随项目版本控制共享给团队
+
+
+### 用户级扩展目录
+
+#### `agents/`
+
+存放对所有项目生效的用户级自定义子代理。每个代理为一个 `.md` 文件：
+
+```
+~/.codebuddy/agents/
+├── code-reviewer.md      # 代码审查代理
+└── translator.md         # 翻译代理
+```
+
+文件格式（YAML frontmatter + 系统提示）：
+
+```markdown
+---
+name: code-reviewer
+description: 代码审查专家，在编写代码后主动使用
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+你是一位高级代码审查员，专注于代码质量、安全性和最佳实践...
+```
+
+详见 [子代理文档](sub-agents.md)。
+
+#### `rules/`
+
+存放对所有项目生效的用户级规则文件。所有 `.md` 文件自动加载，支持子目录：
+
+```
+~/.codebuddy/rules/
+├── preferences.md        # 个人编码偏好
+└── workflows.md          # 常用工作流规范
+```
+
+规则文件支持 frontmatter 控制加载行为：
+
+```markdown
+---
+alwaysApply: false
+paths: src/**/*.ts
+---
+
+# TypeScript 规范
+
+- 优先使用 `interface` 而非 `type`
+- 禁止使用 `any`
+```
+
+详见 [记忆管理 - 规则系统](memory.md#使用-codebuddyrules-实现模块化规则)。
+
+#### `skills/`
+
+存放对所有项目生效的用户级技能。每个技能为独立目录，包含 `SKILL.md`：
+
+```
+~/.codebuddy/skills/
+└── pdf/
+    └── SKILL.md
+```
+
+详见 [Skills 文档](skills.md)。
+
+---
+
+### 运行时数据目录
+
+这些目录由 CodeBuddy Code 自动维护，通常无需手动操作：
+
+| 目录 | 说明 |
+|------|------|
+| `projects/` | 各项目运行时数据，包括会话记录（`.jsonl`）和子代理工具输出（`tool-results/`） |
+| `sessions/` | 活跃会话数据 |
+| `plans/` | 计划模式生成的计划文件 |
+| `logs/` | 运行日志，按日期和进程分组 |
+| `traces/` | OpenTelemetry 执行追踪数据 |
+| `file-history/` | 每个会话中操作过的文件快照，用于 `/rewind` 回退 |
+| `history.jsonl` | 全局对话历史（用于 `/resume` 恢复） |
+| `blobs/` | 图片、截图等二进制资源，按内容哈希存储 |
+| `tasks/` | 任务管理系统数据（TaskCreate/TaskUpdate） |
+| `teams/` | Agent 团队（TeamCreate）运行时数据 |
+| `shell-snapshots/` | Bash 沙箱启动快照，加速沙箱创建 |
+| `plugins/` | 已安装插件的文件内容 |
+| `local_storage/` | CLI 内部键值持久化存储（以内容哈希命名的 `.info` 文件） |
+
+---
+
+## 项目目录 `.codebuddy/`
+
+放置于项目根目录，可以提交到版本控制以供团队共享：
+
+```
+.codebuddy/
+├── settings.json              # 项目共享配置
+├── settings.local.json        # 本地个人配置（.gitignore 自动忽略）
+├── CODEBUDDY.md               # 项目级记忆文件
+│
+├── agents/                    # 项目级自定义子代理
+├── rules/                     # 项目级规则文件
+├── skills/                    # 项目级技能
+├── commands/                  # 自定义斜杠命令
+```
+
+### 配置文件
+
+#### `settings.json`
+
+项目共享配置，通过版本控制与团队同步。适合配置项目统一的模型、权限规则、插件等：
+
+```json
+{
+  "permissions": {
+    "allow": ["Read", "Edit", "Bash(git:*)", "Bash(npm:*)"],
+    "deny": ["Read(./.env)", "Read(./secrets/**)"]
+  },
+  "enabledPlugins": {
+    "pr-review-toolkit@company-tools": true
+  },
+  "extraKnownMarketplaces": {
+    "company-tools": {
+      "source": {
+        "source": "github",
+        "repo": "myorg/codebuddy-plugins"
+      }
+    }
+  }
+}
+```
+
+#### `settings.local.json`
+
+本地个人配置，CodeBuddy Code 会自动将其加入 `.gitignore`。适合存储个人覆盖项（如本地调试端口、个人密钥等），不会影响团队其他成员。
+
+#### `CODEBUDDY.md`
+
+项目级记忆文件，随版本控制共享。存储项目架构、约定、常用命令等团队知识：
+
+```markdown
+# 项目说明
+
+本项目是 TypeScript monorepo（Yarn workspaces）。
+
+## 常用命令
+
+- `yarn build` — 构建所有包
+- `yarn test` — 运行所有测试
+
+## 架构约定
+
+- 使用 CellJS 依赖注入框架
+- 协议定义放在 `*-protocol.ts` 文件
+```
+
+> **提示**：也可将记忆文件放在根目录的 `CODEBUDDY.md`（不在 `.codebuddy/` 内），两种位置等效。
+
+---
+
+### 项目级扩展目录
+
+#### `agents/`
+
+存放项目专属子代理，优先级高于用户级代理。同名代理时项目级覆盖用户级。
+
+```
+.codebuddy/agents/
+├── blog-translator.md     # 博客翻译代理
+└── docs-reviewer.md       # 文档审查代理
+```
+
+#### `rules/`
+
+存放项目级规则，随版本控制共享。适合团队统一的代码规范、工作流约定等。支持子目录组织：
+
+```
+.codebuddy/rules/
+├── code-style.md          # 代码风格规范
+├── testing.md             # 测试规范
+├── security.md            # 安全要求
+└── frontend/
+    ├── react.md           # React 组件规范
+    └── styles.md          # 样式规范
+```
+
+所有 `.md` 文件自动递归加载。
+
+#### `skills/`
+
+存放项目级技能，每个技能一个目录，包含 `SKILL.md` 和可选的辅助文件：
+
+```
+.codebuddy/skills/
+├── case-executor/
+│   ├── SKILL.md           # 技能定义
+│   ├── scripts/           # 辅助脚本
+│   └── references/        # 参考资料
+└── cnb-api/
+    └── SKILL.md
+```
+
+`SKILL.md` 格式：
+
+```markdown
+---
+name: case-executor
+description: 执行 JSON 测试用例并生成报告
+allowed-tools: Read, Write, Bash
+---
+
+你是测试执行专家，负责运行 JSON 格式的 UI 测试用例...
+```
+
+详见 [Skills 文档](skills.md)。
+
+#### `commands/`
+
+存放自定义斜杠命令，通过 `/command-name` 触发。支持目录嵌套（使用 `/group:command` 调用）：
+
+```
+.codebuddy/commands/
+├── deploy.md              # /deploy 命令
+├── team/
+│   ├── issue-start.md     # /team:issue-start 命令
+│   └── create-issue.md    # /team:create-issue 命令
+└── openspec/
+    └── propose.md         # /openspec:propose 命令
+```
+
+命令文件格式：
+
+```markdown
+---
+description: 创建一个新的 Issue
+argument-hint: "<描述> ; <类型> ; <产品>"
+allowed-tools: Bash
+---
+
+根据以下描述创建 Issue：$ARGUMENTS
+```
+
+详见 [斜杠命令文档](slash-commands.md)。
+
+---
+
+## 配置优先级
+
+多层配置按以下优先级应用（高优先级覆盖低优先级）：
+
+```
+命令行参数                         （最高优先级）
+    ↓
+.codebuddy/settings.local.json    （项目本地，不提交版本控制）
+    ↓
+.codebuddy/settings.json          （项目共享，团队统一）
+    ↓
+~/.codebuddy/settings.json        （用户全局，个人偏好）
+    ↓
+产品内置默认配置                   （最低优先级）
+```
+
+代理/技能/规则的优先级：**项目级 > 用户级 > 插件级**，同名时项目级优先。
+
+## 记忆加载顺序
+
+```
+1. 用户级记忆：~/.codebuddy/CODEBUDDY.md
+2. 用户级规则：~/.codebuddy/rules/*.md（递归）
+3. 项目级记忆：CODEBUDDY.md（从 cwd 向上递归查找）
+4. 项目级规则：.codebuddy/rules/*.md（仅 cwd，不向上）
+5. 项目本地记忆：CODEBUDDY.local.md
+6. 子目录记忆：工具操作文件时动态加载该子目录的 CODEBUDDY.md
+```
+
+## 版本控制建议
+
+| 文件/目录 | 是否提交版本控制 | 说明 |
+|-----------|:---:|------|
+| `.codebuddy/settings.json` | ✅ 建议提交 | 团队共享配置 |
+| `.codebuddy/settings.local.json` | ❌ 不提交 | 自动添加至 .gitignore |
+| `CODEBUDDY.md` / `.codebuddy/CODEBUDDY.md` | ✅ 建议提交 | 团队共享知识 |
+| `CODEBUDDY.local.md` | ❌ 不提交 | 自动添加至 .gitignore |
+| `.codebuddy/agents/` | ✅ 建议提交 | 团队共享子代理 |
+| `.codebuddy/rules/` | ✅ 建议提交 | 团队共享规则 |
+| `.codebuddy/skills/` | ✅ 建议提交 | 团队共享技能 |
+| `.codebuddy/commands/` | ✅ 建议提交 | 团队共享命令 |
+
+## 相关资源
+
+- [设置配置](settings.md) — 完整的配置字段参考
+- [记忆管理](memory.md) — CODEBUDDY.md 和规则系统详解
+- [子代理](sub-agents.md) — 创建和使用自定义子代理
+- [Skills 文档](skills.md) — 技能系统详解
+- [斜杠命令](slash-commands.md) — 自定义命令参考
+- [MCP 文档](mcp.md) — MCP 服务器配置
+
+---
+
+*合理利用 `.codebuddy` 目录，让 CodeBuddy Code 更了解你的项目和团队规范。*

package/cli/dist/web-ui/docs/cn/cli/env-vars.md

@@ -41,6 +41,8 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `BASH_MAX_TIMEOUT_MS` | 模型可为长时间运行的 bash 命令设置的最大超时（默认：600000） |
 | `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | 主对话响应预算（毫秒，默认 `0`=关闭）。设为 `>0` 时，主会话的前台 Bash/PowerShell 命令超过该时长会自动转为后台任务让对话保持响应。sub-agent 不受此预算影响。对齐 Claude Code 的 `ASSISTANT_BLOCKING_BUDGET_MS`（CC 官方默认值 `15000`） |
 | `CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED` | 设为 `1` 关闭超时自动后台化,前台命令到 timeout 回到旧的 SIGTERM/kill 硬杀行为。仅用于调试或遇到回归时临时回滚；正常场景保持默认（未设置） |
+| `CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTES` | 后台 bash 任务 stdout+stderr 落盘文件总字节上限（默认 `52428800` = 50MB）。超过则 size watchdog 触发 `SIGKILL` 并标记任务为 `killed`，stderr 末尾会注入提示。Claude Code 在 `ShellCommand.ts` 把同等阈值写死为常量，这里暴露为 env 给运维做调节。仅在文件 fd 模式生效（pipe 模式下子进程输出不落盘） |
+| `CODEBUDDY_BASH_BG_PIPE_MODE` | 设为 `1` 强制后台任务回到 pipe 模式（不走文件 fd），用于回滚或调试。默认（未设置）走文件 fd 模式，解决 nohup 等命令孙进程持有父 pipe fd 导致僵尸进程的问题；sandbox 路径会自动回退 pipe，不需要显式设置。Claude Code 没有等价开关，这是 codebuddy 兼容旧 sandbox/PTY 路径的兜底 |
 
 ## 工具输出外部化
 
@@ -64,6 +66,7 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `CODEBUDDY_DEFER_TOOL_LOADING` | 设置为 `false` 或 `0` 禁用 MCP 工具延迟加载 |
 | `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | 设置为 `true` 或 `1` 显示所有延迟工具的完整描述 |
 | `CODEBUDDY_DISABLE_CRON` | 设置为 `1` 禁用计划任务 |
+| `CODEBUDDY_DISABLE_FORK_SUBAGENT` | 设置为 `1` 禁用 Agent 工具的 Fork 子代理模式（`subagent_type="fork"`）。启用后 Agent 工具描述会自动隐藏 fork-mode 段落，模型不会看到该功能；若模型仍然传 `subagent_type="fork"`，运行时会回落到名为 `fork` 的自定义代理（如用户在 `.codebuddy/agents/fork.md` 定义），否则改写为 `general-purpose` 普通子代理。适用于需要避免 fork 递归派生导致请求量放大的宿主场景 |
 | `CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFS` | 设置为 `true` 在 `-p` 模式流式输出中将图片 blob 引用还原为完整 base64 数据。适用于需要直接获取图片数据的下游集成场景 |
 
 ## 上下文和内存
@@ -145,6 +148,24 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `DISABLE_AUTOUPDATER` | 设置为 `1` 禁用自动更新 |
 | `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 禁用 `/feedback` 命令 |
 
+### OpenTelemetry 自定义上报（traces）
+
+CodeBuddy Code 支持把内部 traces 通过 OTLP 协议上报到用户自有的 Collector，环境变量遵循 [OpenTelemetry 规范](https://opentelemetry.io/docs/specs/otel/protocol/exporter/)。详细使用方式见 [Monitoring](monitoring.md)。
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_CODE_ENABLE_TELEMETRY` | 设置为 `1` 启用 OTel 自定义上报；为兼容从 Claude Code 迁移的客户，`CLAUDE_CODE_ENABLE_TELEMETRY` 同样生效 |
+| `OTEL_TRACES_EXPORTER` | `otlp`（默认）/ `console`（输出到日志，便于调试）/ `none`（关闭） |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | 通用 OTLP endpoint，工具会自动追加 `/v1/traces` |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | traces 专用 endpoint，作为完整 URL 使用，优先级高于通用变量 |
+| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP 请求头，格式 `k1=v1,k2=v2`，value 支持 URL 编码 |
+| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | traces 专用请求头，优先级高于通用变量 |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | 仅支持 `http/protobuf`（默认）；其他值（如 `grpc`、`http/json`）会回退并打告警 |
+| `OTEL_SERVICE_NAME` | 覆盖默认 `service.name` |
+| `OTEL_RESOURCE_ATTRIBUTES` | 资源属性，格式 `k1=v1,k2=v2`，会合并进 trace resource |
+
+> 当 `DISABLE_TELEMETRY=1` 时，无论上述变量如何设置，OTel 上报均关闭。
+
 ## 任务和后台工作
 
 | 环境变量 | 说明 |

package/cli/dist/web-ui/docs/cn/cli/goal.md

@@ -0,0 +1,161 @@
+# 让 CodeBuddy 持续工作直到达成目标
+
+> 用 `/goal` 设置一个完成条件，CodeBuddy 会跨多轮持续工作，直到条件满足才把控制权交还给你。
+
+> **版本要求**：`/goal` 命令要求 `@tencent-ai/codebuddy-code` 已包含 goal 功能（agent-cli 的 `GoalService` 模块）。
+
+`/goal` 命令设置一个完成条件，CodeBuddy 持续向其推进而无需你逐步催促。每轮（turn）结束时，由小模型（small-fast model）评估器判断条件是否成立——若不成立，CodeBuddy 自动开始下一轮，而不是把控制权交回给你。一旦条件满足，目标自动清除。
+
+适合用 `/goal` 跟踪有可验证终态的实质性工作：
+
+- 把一个模块迁到新 API，直到所有调用点都能编译且测试通过
+- 实施一份设计文档，直到所有验收条件成立
+- 把一个大文件拆成若干聚焦模块，直到每个模块都不超过尺寸预算
+- 处理打了某个标签的 issue 列表，直到队列清空
+
+本文涵盖：
+
+- [与其他自治工作流对比](#与其他自治工作流对比)：`/goal`、`/loop`、Stop hook 三者怎么选
+- [设置目标](#设置目标)与[写好条件的要点](#写好一个有效的-condition)
+- [查看状态](#查看状态)、[提前清除](#提前清除目标)、[非交互模式运行](#非交互模式运行)
+- [评估机制](#评估机制如何工作)
+- [实现说明与已知限制](#实现说明与已知限制)
+
+
+## 使用 `/goal`
+
+每个会话同时只能有一个 active goal。同一个命令根据参数差异承担"设置 / 查看 / 清除"三种角色。
+
+### 设置目标
+
+在 `/goal` 后跟你想满足的条件即可。如果当前已有 active goal，新的会替换旧的（旧 goal 的 hook 自动注销）。
+
+```text
+/goal all tests in test/auth pass and the lint step is clean
+```
+
+设置完成后，CodeBuddy 会**立即开始一轮**，把"条件本身"作为指令交给主 agent——不需要你再额外发 prompt。同时输入框右下方会出现一行 `⊚ /goal active (Xs)` 指示器，每秒刷新已运行时长，让你随时知道当前处于 goal 模式。
+
+每轮结束后，评估器会返回一段简短的 reason 解释"为什么条件还没/已满足"。这段 reason 会以 `isMeta=true` 的内部消息形式注入对话历史，让模型在下一轮看到 evaluator 的视角，从而精准补做欠缺的部分——这是模型能"知道还差哪几步"的关键。
+
+> **会话级行为**：goal 持续运行直到条件满足或你执行 `/goal clear`。运行 `/goal`（无参数）查看 turns / tokens 等统计。
+
+### 写好一个有效的 condition
+
+[评估器](#评估机制如何工作)只会基于 CodeBuddy 在对话中**已经表达出来**的内容来判断条件，它不会自己跑命令、读文件。所以条件要写成"CodeBuddy 自己的输出能证明"的形式。"All tests in `test/auth` pass" 之所以可行，是因为 CodeBuddy 会自己跑测试，结果落在 transcript 里供评估器阅读。
+
+一个能稳健支撑多轮工作的条件通常包含：
+
+- **一个可度量的终态**：测试结果、构建退出码、文件数、空队列……
+- **一种可证明方式**：例如 ``\`npm test\` exits 0`` 或 ``\`git status\` is clean``
+- **不可破坏的约束**：路上不能改的东西，比如 "no other test file is modified"
+
+condition 长度上限 **4000 字符**。
+
+如果想给 goal 设置兜底上限，可以在 condition 里加上轮数 / 时间从句，例如 `or stop after 20 turns`，CodeBuddy 会在每轮里把当前进度对照该从句，evaluator 也能从对话中读出。
+
+### 查看状态
+
+不带参数运行 `/goal`：
+
+```text
+/goal
+```
+
+在 TUI 中会打开 goal recap 面板；在 Web UI / ACP 客户端中会通过 ACP 广播打开同等面板；在 headless / SDK 等没有 UI 的环境降级为纯文本输出。
+
+面板内容包括：
+- 条件
+- 已运行时长
+- 已评估的 turn 数
+- token 消耗（goal 期间增量）
+- 评估器最近一次给出的 reason
+
+如果当前没有 active goal、但本会话内之前曾达成过一次 goal，面板会展示那次的 condition、duration、turn 数和 token 数。
+
+### 提前清除目标
+
+```text
+/goal clear
+```
+
+下面这些 token 都视为 `clear` 的同义词：`stop`、`off`、`reset`、`none`、`cancel`。仅在**单 token 完全匹配**时识别为清除指令——`/goal stop using deprecated API` 仍按"设置新 condition"处理，不会被吞掉。
+
+执行 `/clear` 重启会话也会一并移除 active goal（hook 注销 + meta 清理）。
+
+### 在恢复会话时携带 goal
+
+通过 `--resume` / `--continue` 恢复会话时，未完成的 goal 会被恢复（condition 与 scope 都还原）。
+
+> **当前限制**：恢复时会沿用原 goal 的 createdAt / turnCount / token 起点，不重置计时器与计数器。如果你希望"重新计时"，请先 `/goal clear` 再重新 `/goal <condition>`。已经达成或已被清除的 goal 不会被恢复（meta 已删）。
+
+### 非交互模式运行
+
+`/goal` 在[非交互模式（headless）](./headless.md)、[Remote Control](./remote-control.md) 中均可用。在 `-p` 模式下设置 goal 会让 evaluator 循环跑到完成：
+
+```bash
+codebuddy -p "/goal CHANGELOG.md has an entry for every PR merged this week"
+```
+
+需要在条件满足前提早终止，按 `Ctrl+C`。
+
+---
+
+## 评估机制如何工作
+
+`/goal` 是对会话级 [prompt-based Stop hook](./hooks.md) 的一层封装。每当 CodeBuddy 主 agent 跑完一轮，**当前 condition + 当前对话** 会被一并发给配置好的小模型评估器。评估器返回一个"是 / 否 / 不可达"三态结果与简短 reason：
+
+- **是（`ok: true`）**：清除 goal、记录"已达成"事件，UI 显示 `✔ Goal achieved` 状态条。
+- **否（`ok: false`）**：把 reason 作为 `isMeta=true` 的 user message 注入 history（让主模型看到下一步该补什么），让 CodeBuddy 继续工作。同时写入一条 `goal-progress` UI 状态条 `◯ Goal not yet met… continuing`。
+- **不可达（`ok: false, impossible: true`）**：用于评估器判断"在当前会话里这个目标根本不可能完成"（条件自相矛盾、依赖的能力/资源不可用、模型已经穷尽合理尝试）。立即清除 goal，UI 显示 `✕ Goal could not be achieved`，避免把循环陷死。
+
+评估器使用 product 配置中绑定到 **`lite` 槽位**的小模型（在不同 model provider 上分别映射到 `gpt-5.1-codex-mini` / `gemini-2.5-flash` / DeepSeek `deepseek-v4-flash` 等）。评估只看现有 transcript、不调用工具，所以走小模型既快又便宜。
+
+> **计费**：评估器消耗的 token 计在小模型账单上，相对主 turn 通常可忽略。
+
+### 评估窗口约束
+
+为了避免"刚 set 完就 achieved"——同一会话曾经达成过的目标会在 transcript 里留下成功响应——我们会把当前 goal 的 `createdAt`（ISO 8601）注入评估器的 user prompt，并明确指示：
+
+> Evaluate ONLY the conversation that happened AFTER this timestamp. Earlier messages MUST NOT be used as evidence.
+
+如果设置后还没有合格活动发生，evaluator 必须返回 `{"ok": false, "reason": "Goal was just set; no work has been done yet against the new condition."}`。
+
+### 给 evaluator 的 history 干净化
+
+我们会在把 history 喂给 evaluator 前过滤掉以下扩展 item type（它们是项目自定义、SDK 不认识的）：
+
+- `goal-result` / `goal-progress`（goal 自身的 UI 状态项）
+- `summary` / `topic` / `ai-title` / `custom-title`
+- `file-history-snapshot`
+
+这些 item 既不是用户输入也不是 assistant 响应，对 evaluator 没有判断价值，且会触发 SDK 的 `Unknown item type` 警告。
+
+---
+
+## 实现说明与已知限制
+
+下表汇总当前实现的关键行为与已知限制，便于排错时定位：
+
+| 行为 | 状态 | 备注 |
+| :--- | :--- | :--- |
+| 设置 / 替换 / kick-off | ✅ | 设置后立即开始一轮，已有 active goal 时自动替换 |
+| `/goal clear` 别名 | ✅ | 支持 stop / off / reset / none / cancel 五种单 token 同义词 |
+| `/clear` 同步清除 active goal | ✅ | 重启会话时一并注销 goal hook 并清理 meta |
+| condition 上限 | ✅ | 4000 字符 |
+| reason 反馈进 history | ✅ | 注入格式：`Stop hook feedback: [<condition>]: <reason>` |
+| 三态语义（ok / not-yet / impossible） | ✅ | 不可达时立即清除 goal，避免无效循环 |
+| evaluator 走小模型 | ✅ | 使用 `lite` 槽位绑定的模型（按 provider 分别映射） |
+| `/goal` 无参 → 状态视图 | ✅ | TUI / Web UI 面板 + headless 文本降级 |
+| 持续运行指示器 `⊚ /goal active (Xs)` | ✅ | 输入框右下方常驻显示运行时长，1Hz 刷新 |
+| `--resume` 时 turn / timer / token 重置 | ❌ 待补 | 当前沿用原 createdAt / turnCount，需"重新计时"请先 `/goal clear` |
+
+---
+
+## 参见
+
+- [`/loop` 创建循环任务](./scheduled-tasks.md#使用-loop-创建循环任务)：按时间间隔重复触发，而不是直到条件满足
+- [Hook 入门](./hooks-guide.md) / [Hook 参考](./hooks.md)：理解 prompt-based Stop hook 的底层机制；当你需要更复杂的评估逻辑时可以自己写一个
+- [非交互（headless）模式](./headless.md)：在 CI / 脚本中通过 `-p` 跑 `/goal`
+- [Remote Control](./remote-control.md)：在 Web UI / 微信通道中触发 goal
+- [斜杠命令一览](./slash-commands.md)：所有内置 slash 命令的索引

package/cli/dist/web-ui/docs/cn/cli/hooks.md

@@ -1,9 +1,9 @@
 # Hook 参考指南
 
-> **版本要求**：本文档针对 CodeBuddy Code v1.16.0 及以上版本中提供的 Claude Code Hooks 兼容实现。
+> **版本要求**：本文档针对 CodeBuddy Code v1.16.0 及以上版本中提供的 Hooks 实现。
 > **功能状态**：Hook 功能当前处于 **Beta** 阶段，接口和行为可能在未来版本中调整。
 
-Hook（钩子）允许你在 CodeBuddy Code 的会话生命周期内插入自定义脚本或命令，实现自动化校验、环境初始化、合规检查等高级能力。我们的实现完全兼容 Claude Code Hooks 规范，支持相同的事件类型、输入输出结构以及安全特性。
+Hook（钩子）允许你在 CodeBuddy Code 的会话生命周期内插入自定义脚本或命令，实现自动化校验、环境初始化、合规检查等高级能力。
 
 
 ## 配置
@@ -142,11 +142,13 @@ Hooks 按匹配器组织，每个匹配器可以有多个 hooks:
 
 > **支持的事件**：目前仅支持 `Stop`、`UserPromptSubmit` 和 `PreToolUse` 三种事件。
 
+> **会话级捷径**：内置斜杠命令 [`/goal`](./goal.md) 是 prompt-based Stop hook 的开箱即用封装——直接输入 `/goal <condition>` 即可让 CodeBuddy 持续工作直到条件满足，无需手写 hook 配置。如果你的判定逻辑可以靠条件文本表达，优先用 `/goal`；只有需要更复杂的 prompt 编排或跨多事件协作时才回到本节自己写 prompt hook。
+
 ### 基于提示词的 hooks 如何工作
 
 基于提示词的 hooks 不是执行 bash 命令，而是：
 
-1. 将 hook 输入和你的提示词发送给快速 LLM（Haiku）
+1. 将 hook 输入和你的提示词发送给快速小模型（绑定到 `lite` 槽位的小模型，按 model provider 分别映射）
 2. LLM 使用包含决策的结构化 JSON 响应
 3. CodeBuddy Code 自动处理决策
 
@@ -203,7 +205,8 @@ LLM 必须使用包含以下内容的 JSON 响应：
 ```jsonc
 {
   "ok": true | false,
-  "reason": "Explanation for the decision"  // 当 ok 为 false 时必需
+  "reason": "Explanation for the decision",  // 当 ok 为 false 时必需
+  "impossible": false                          // 可选，仅 Stop 事件下生效
 }
 ```
 
@@ -211,6 +214,9 @@ LLM 必须使用包含以下内容的 JSON 响应：
 
 - `ok`：`true` 允许操作，`false` 阻止操作
 - `reason`：当 `ok` 为 `false` 时必需，显示给 CodeBuddy 的解释
+- `impossible`：可选布尔值，仅 `Stop` hook 下有意义。`{ok: false, impossible: true}` 表示评估器判断"在当前会话里这个目标根本不可能完成"（条件自相矛盾、依赖资源不可用、模型已穷尽合理尝试）。CodeBuddy 不再继续循环，UI 显示"无法达成"终态。普通 `{ok: false}` 仍按"未达成、继续工作"处理。
+
+**reason 注入 history 的语义**：`Stop` hook 返回 `{ok: false}` 时，`reason` 文本不是简单地"显示给 CodeBuddy"——它会以 `isMeta=true` 的内部 user message 形式注入到对话 history 中，让主模型在下一轮看到评估器的视角，从而精准补做欠缺的部分。这是 prompt-based Stop hook 能驱动多轮迭代收敛的核心机制（`/goal` 命令底层就是依赖这条链路）。
 
 ### 示例：智能 Stop Hook
 
@@ -362,6 +368,8 @@ LLM 必须使用包含以下内容的 JSON 响应：
 
 在主 CodeBuddy Code 代理完成响应时运行。如果停止是由于用户中断而发生的，则不会运行。
 
+> **会话级捷径**：内置斜杠命令 [`/goal`](./goal.md) 是 session-scoped prompt-based Stop hook 的封装——`/goal <condition>` 一行即可注册一个让 CodeBuddy 持续工作到条件满足为止的 Stop hook，并自动处理三态评估（达成 / 未达成继续 / 不可达成）、turn 计数、token 统计、`/resume` 自动恢复等细节。需要会话级"持续工作直到 X"时优先考虑 `/goal`，不必手写 hook 配置。
+
 ### SubagentStop
 
 在 CodeBuddy Code 子代理(Agent 工具调用）完成响应时运行。

package/cli/dist/web-ui/docs/cn/cli/http-api.md

@@ -287,6 +287,7 @@ CBC 增强：
 | GET | `/api/v1/plugins/marketplaces` | 列出已配置的插件市场 |
 | POST | `/api/v1/plugins/marketplaces` | 添加插件市场 |
 | POST | `/api/v1/plugins/marketplaces/browse` | 浏览市场中的可用插件 |
+| POST | `/api/v1/plugins/marketplaces/update` | 更新市场（同步远端仓库内容） |
 | DELETE | `/api/v1/plugins/marketplaces/:name` | 删除插件市场 |
 
 ### 配置管理
@@ -547,6 +548,11 @@ curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/browse \
   -H "Content-Type: application/json" \
   -d '{"marketplace": "my-marketplace"}'
 
+# 更新市场（真正从远端拉取最新内容）
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/update \
+  -H "Content-Type: application/json" \
+  -d '{"marketplace": "my-marketplace"}'
+
 # 删除插件市场
 curl -X DELETE http://127.0.0.1:8080/api/v1/plugins/marketplaces/my-marketplace
 ```

package/cli/dist/web-ui/docs/cn/cli/ide-integrations.md

@@ -42,7 +42,8 @@ codebuddy --ide
 
 - CodeBuddy 会在当前用户目录下扫描由 IDE 插件创建的锁文件，检测可用的 IDE 实例
 - 仅当 IDE 的工作区包含当前目录时才认为是「有效 IDE」
-- 优先连接「工作区匹配且进程链路为当前终端上游」的 IDE
+- 仅当**恰好一个**有效 IDE 匹配当前工作目录时才会自动连接；如果零个或多个匹配，自动连接将静默跳过，您可以使用 `/ide` 手动选择
+- 检测前会自动清理已退出的 IDE 进程对应的过期锁文件，避免连到无效端口
 - 连接成功后，CLI 会通过 IDE MCP 服务器获得：
   - 文件/差异预览 （openFile / openDiff)
   - 诊断信息 （getDiagnostics)