@foxden-app/foxclaw 0.11.1 → 0.13.0

package/docs/zh/dsh.md

@@ -0,0 +1,83 @@
+# DeepSeek Harness 后端
+
+FoxClaw 直接启动 DSH 的 `acp` profile，复用 Telegram 的任务进度、工具状态、最终回答、排队和中断功能。模型与推理档位读取 DSH 当前会话提供的选项；每个 Bot、聊天和话题分别保存会话与设置。
+
+## 接入现有 Bot
+
+在 FoxClaw 的 `.env` 中增加：
+
+```dotenv
+DSH_ENABLED=true
+DSH_SOURCE_DIR=/absolute/path/to/deepseek-harness
+```
+
+DSH 源码目录需已安装依赖并准备好本机 native addon。源码模式使用 FoxClaw 的 Node 启动 `apps/cli/src/bin.ts`，从 DSH 目录加载 `tsx`。Linux 开发环境可先在 DSH 仓库执行 `pnpm install` 和 `pnpm run build:native-system`，其他平台按 DSH 自身安装说明准备。
+
+如果使用已安装的 CLI，则用 `DSH_CLI_BIN=/absolute/path/to/dsh` 替代 `DSH_SOURCE_DIR`；也支持 CLI 的 `.js`、`.mjs` 或 `.cjs` 入口。两项同时设置时优先源码目录。
+
+重启 FoxClaw 后，在现有 Codex 或 Antigravity Bot 中发送 `/backend dsh`，再发送 `/setup`。切回原后端后，原后端的会话和设置会恢复。正在执行任务时，先 `/interrupt` 再切换后端。
+
+## 独立 DSH Bot
+
+```dotenv
+CODEX_BOT_TOKENS=
+DSH_BOT_TOKEN=123456:your-independent-bot-token
+DSH_SOURCE_DIR=/absolute/path/to/deepseek-harness
+TG_ALLOWED_USER_ID=123456789
+DEFAULT_CWD=/absolute/path/to/workspace
+```
+
+`DSH_BOT_TOKEN` 自动启用 DSH，必须与其他后端的 Bot token 不同。独立 DSH 模式无需 Codex 或 Antigravity；执行 `foxclaw doctor` 检查，再正常启动服务。当前 DSH 接入范围是 Telegram，微信仍使用已有后端。
+
+## 配置与操作
+
+| 配置 | 默认值 / 用途 |
+| --- | --- |
+| `DSH_HOME` | DSH 原有 home，通常 `~/.dsh`；复用其凭据、profile 和持久会话 |
+| `DSH_PROFILE` | `acp`；自定义 profile 必须提供 ACP、模型控制和 `permissionPresets` 服务 |
+| `DSH_PATCHES` | JSON 数组，如 `["/absolute/path/to/patch.yml"]`；按顺序传入 DSH |
+| `DSH_STARTUP_TIMEOUT_MS` | `60000`；首次初始化 profile 的最长等待时间 |
+| `DEFAULT_SANDBOX_MODE` | 初始权限，支持 `read-only`、`workspace-write`、`danger-full-access` |
+
+Provider 与 API key 沿用 DSH 配置。使用环境变量的 provider，可将相应变量（如 `DEEPSEEK_API_KEY`）加入 FoxClaw `.env`，DSH 子进程会继承。这里不使用 Codex/AGY 的账号轮转或认证同步。
+
+| 操作 | 用途 |
+| --- | --- |
+| `/setup` | 模型、推理档位、权限、排队/中断接管、会话与插件配置面板 |
+| `/models`、`/model <provider/model>` | 选择 DSH 模型；`/model default` 恢复会话初始模型 |
+| `/effort`、`/effort <档位>` | 使用当前模型提供的推理档位；切换模型会重置为该模型默认档位 |
+| `/permissions read-only|default|full-access` | 只读、工作区写入、完全访问；也可从面板选择 |
+| `/threads`、`/open <会话 ID>` | 列出并恢复 DSH 持久会话 |
+| `/new [目录]` | 新会话，可指定工作目录 |
+| `/active queue|steer`、`/queue`、`/steer <消息>`、`/interrupt` | 排队、中断接管与取消 |
+| `/plugins` | 查看 profile 显式插件依赖和额外 patch 路径 |
+
+权限通过随桥加载的 `foxclaw-permissions` 插件设置 DSH 原生 preset，作用于根 Agent，子 Agent 按 DSH 自身规则继承。DSH 发出的工具审批会显示“允许本次 / 拒绝”按钮，中断或退出时取消等待中的审批。任务执行中不能修改权限。
+
+## 插件与支持边界
+
+`/plugins` 展示 profile 的显式依赖和配置 patch，并非所有运行中的内置插件清单。安装或移除沿用 DSH 命令，使用与 FoxClaw 一致的 `DSH_HOME` 和 profile，完成后重启 FoxClaw：
+
+```bash
+dsh plugin --profile acp add <package>
+dsh plugin --profile acp remove <package>
+```
+
+源码模式下，可用 `node --import tsx/esm apps/cli/src/bin.ts plugin --profile acp ...` 在 DSH 仓库执行。FoxClaw 目前不提供聊天内安装/移除插件按钮。
+
+进度来自 ACP 的已提交消息和工具事件，不是模型原始 token 流。图片在 ACP 声明支持时原生发送，其余附件传入本地路径。DSH 当前 ACP 未提供历史消息回放、会话分叉、重命名、Agent/Plan 切换等接口；对应 Codex 专用按钮不会出现在 DSH 面板。
+
+ACP 当前仅报告上下文占用，不提供逐轮输入、输出及缓存 token 消耗；DSH 状态页会明确说明统计未提供。
+
+## 开发验证
+
+普通 DSH 测试使用不需要 API key 的 ACP 子进程 fixture。真实源码联调使用 DSH 自带的控制面 fixture，不调用付费模型：
+
+```bash
+FOXCLAW_DSH_TEST_SOURCE_DIR=/absolute/path/to/deepseek-harness \
+DSH_TELEMETRY_DISABLED=1 node --test --import tsx src/dsh/source.integration.test.ts
+```
+
+联调使用临时 home 和会话目录，验证模型/推理设置、原生权限日志、恢复、工具事件和取消。未配置源码路径时跳过此项。
+
+先执行 `npm run build`，再追加 `FOXCLAW_DSH_TEST_BUILT=1` 可验证编译后的后端和随包发布的权限插件。

package/docs/zh/release.md

@@ -16,38 +16,40 @@
 
 ```bash
 git status --short --branch
-npm pkg get name version
-npm view @foxden-app/foxclaw version
+node -p "require('./package.json').name + '@' + require('./package.json').version"
+pnpm view @foxden-app/foxclaw version
 git tag --list 'v*' --sort=-v:refname | head
 ```
 
 确认目标版本还没有发布，也没有远端 tag：
 
 ```bash
-npm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
+pnpm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
 git ls-remote --tags origin refs/tags/v0.5.10
 ```
 
+使用 `packageManager` 固定的 pnpm 版本，以 `pnpm install --frozen-lockfile` 安装依赖。发布流水线仅在 registry 鉴权和发布步骤使用 npm。
+
 运行与发布 workflow 对齐的本地校验：
 
 ```bash
-npm run lint
-npm run typecheck
-npm test
-npm pack --dry-run
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm pack --pack-destination /tmp/foxclaw-release
 git diff --check
 ```
 
-`npm pack --dry-run` 会执行 `prepack` 构建，并列出 npm 包内容。确认输出里有 `CHANGELOG.md`。
+`pnpm pack` 会执行 `prepack` 构建并创建发布包。使用 `tar -tzf /tmp/foxclaw-release/*.tgz` 检查包含 `CHANGELOG.md`。
 
 ## 准备版本
 
-1. 更新 `package.json` 和 `package-lock.json` 的版本号。
+1. 更新 `package.json` 和 `pnpm-lock.yaml` 的版本号。
 2. 在 `CHANGELOG.md` 顶部新增版本条目，包含 `### 中文` 和 `### English` 小节。
 3. 提交发布 commit，推荐格式：
 
 ```bash
-git add package.json package-lock.json CHANGELOG.md
+git add package.json pnpm-lock.yaml CHANGELOG.md
 git commit -m "发布 0.5.10：一句话说明"
 ```
 
@@ -71,7 +73,7 @@ gh run watch <run-id> --repo foxden-app/foxclaw --exit-status
 成功后确认 npm 和 GitHub Release：
 
 ```bash
-npm view @foxden-app/foxclaw version
+pnpm view @foxden-app/foxclaw version
 gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
 ```
 

package/docs/zh/telegram-experience.md

@@ -0,0 +1,40 @@
+# Telegram 主通道：能力评估与接入顺序
+
+日期：2026-10-06。Telegram 是主使用通道；微信保留文字菜单基础，观察模式的消息收纳方案明确后再扩展。
+
+## 官方能力与 FoxClaw 的用途
+
+官方最新列出的版本为 Bot API 10.3（2026-08-24）。10.1 加入富消息，10.2 加入群内定向临时消息，10.3 增加草稿停止控制和禁用按钮。[官方更新记录](https://core.telegram.org/bots/api#recent-changes)
+
+| 优先级 | 能力 | 产品用途 | 当前状态与边界 |
+| --- | --- | --- | --- |
+| P0 | 编辑消息、富消息 | 一条任务进度卡，完成后换成结果；保留模型、权限、审批入口 | 统一任务路径已实现；私聊草稿与群聊持久卡分别管理，结果交付前结束预览。存量观察展示待收敛 |
+| P1 | 草稿原生停止按钮 | 手机直接停止正在生成的回复 | 已接入。只停止对应任务，保留排队任务；群聊和草稿不支持时使用卡片按钮。等待原生取消完成后释放任务槽位 |
+| P1 | 折叠内容、结构化块 | 摘要常驻，工具过程和长日志折叠；需要时查看完整结果 | 统一任务已实现回答在前、执行摘要折叠在后；长摘要限长，长回答按需分块。外部观察卡待统一 |
+| P1 | 禁用按钮 | 正在切换账号、启动或取消任务时明确展示暂不可用的操作 | 待接入。后端仍必须验证操作有效性，展示状态不能代替校验 |
+| P2 | 群内仅本人可见的临时面板 | 账号、模型和个人设置不占公共群消息流 | 待接入；需要独立处理临时消息标识、回调用户与删除/编辑接口 |
+| P2 | 复制文本按钮 | 复制工作目录、恢复命令、任务编号 | 按场景加入，优先采用菜单可直接完成的操作 |
+
+草稿停止使用 `can_stop`、`keep_on_stop` 和 `stopped_message_generation` 更新。草稿限私聊且是临时预览，最终回答仍需发送持久消息。停止事件只携带聊天、主题和草稿编号，必须与当前任务匹配，忽略过期事件。[草稿接口](https://core.telegram.org/bots/api#sendrichmessagedraft)、[停止事件](https://core.telegram.org/bots/api#messagegenerationstopped)
+
+禁用按钮和颜色由 Telegram 键盘类型支持；群内个人面板需要定向临时消息及其专用编辑接口。[键盘按钮](https://core.telegram.org/bots/api#inlinekeyboardbutton)、[临时消息参数](https://core.telegram.org/bots/api#ephemeralmessageparameters)
+
+不把这些功能一次性塞入共享调度器。Telegram 通道声明展示能力并转换事件；调度器只处理任务状态、操作归属和取消结果；各后端提供自己的模型、权限与审批能力。
+
+## 推荐的任务与观察展示
+
+1. 每项任务维护一条进度卡：引擎、阶段、耗时、最近一项工具活动、停止入口。
+2. 增量内容合并、节流编辑，普通工具活动不新增聊天消息。
+3. 审批单独展示，保持明确的任务归属；完成后更新或撤销过期操作。
+4. 最终结果显示结论与必要证据，长过程折叠；文件按需提供。
+5. 观察外部会话沿用相同的信息结构，但保持只读语义。新增输入应明确排队或接管，不因展示重构而暗改。
+
+本轮已落地“单条进度卡 → 停止操作 → 完成后折叠摘要”，覆盖 Telegram 的 Codex / AGY / DSH 统一任务路径。草稿使用同一个编号刷新，运行期间保持更新；完成或停止后清除草稿并发送持久结果。停止事件验证允许的私聊、主题和当前草稿；群聊停止回调还验证用户与具体任务编号。旧按钮与旧草稿不会停止后来启动的任务。
+
+暂未接入定向临时设置面板和禁用按钮，存量外部会话观察展示也未统一。原生 API 能力有自动化模拟验证，手机上的实际交互效果需要上线后由用户验收。
+
+## 微信进入实用阶段的条件
+
+微信无法原地编辑进度卡，建议采用“开始提示 → 必要里程碑 → 最终摘要”。合并重复工具消息，不逐段推送生成文本；失败、审批和需要用户介入时即时提示。
+
+已接受使用文字菜单和命令。本轮增加有会话归属、有效期和单次使用约束的 `/choose` 操作。统一观察摘要、历史整理和完整多后端接入保留为后续工作，不先扩大微信使用范围。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.11.1",
-  "description": "Foxden local execution claw for controlling Codex, OpenCode, and Antigravity from trusted chat interfaces.",
+  "version": "0.13.0",
+  "description": "Foxden local execution claw for controlling Codex, OpenCode, Antigravity, and DeepSeek Harness from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",
   "bin": {
@@ -35,7 +35,7 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
     "dev": "tsx src/main.ts serve",
     "serve": "node dist/main.js serve",
     "start-service": "node dist/main.js start",
@@ -52,9 +52,10 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "test": "node --test --import tsx $(find src -name '*.test.ts' -print)",
-    "prepack": "npm run build"
+    "prepack": "pnpm build"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
     "@opencode-ai/sdk": "1.18.15",
     "dotenv": "^16.6.1",
     "qrcode-terminal": "^0.12.0"
@@ -66,5 +67,6 @@
     "tsx": "^4.19.3",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.58.0"
-  }
+  },
+  "packageManager": "pnpm@10.33.2"
 }