@modesto_ma/dsh-guanxiang 0.2.0-beta.3 → 0.2.0-beta.4

package/README.md

@@ -57,11 +57,11 @@
 父 Agent 按应用分节汇总，涉及多个应用时给出跨应用的推演
 ```
 
-- **一个入口，两种触发。** 入口 SKILL 是 `/guanxiang`，dsh 在 Web、TUI、ACP 以及经 dsh_channels 的飞书消息中都能识别它。有可用应用且 `autoInvoke` 开启（默认）时，模型也能自行加载：dsh 给顶层 Agent 的 skill 目录里，观象的描述会列出每个可用应用的名称、id、别名和日志特征（总长不超过 500 字，放不下的只计数），用户说「分析这份订单服务的日志」或贴出带 `OrderController` 的报错时，模型会先加载观象。日志明显不属于任何已注册应用时，入口 SKILL 让模型按普通方式处理，不派发也不追问。子 Agent 的工作目录在 `reposDir` 内，那里不列出观象。应用增删时 dsh 会追加一条新的 skill 目录消息；想要确定触发时仍用 `/guanxiang`。
+- **一个入口，两种触发。** 入口 SKILL 是 `/guanxiang`，dsh 在 Web、TUI、ACP 以及经 dsh_channels 的飞书消息中都能识别它。有可用应用且 `autoInvoke` 开启（默认）时，模型也能自行加载：dsh 给顶层 Agent 的 skill 目录里，观象的描述会列出每个可用应用的名称、id、别名和日志特征（总长不超过 500 字，放不下的只计数），用户说「分析这份订单服务的日志」或贴出带 `OrderController` 的报错时，模型会先加载观象。日志明显不属于任何已注册应用时，入口 SKILL 让模型按普通方式处理，不派发也不追问。子 Agent 的工作目录在 dsh-repo 的镜像目录内，那里不列出观象。应用增删时 dsh 会追加一条新的 skill 目录消息；想要确定触发时仍用 `/guanxiang`。
 - **派发由代码完成。** 模型只给出应用 id、问题和日志位置；仓库目录、应用 SKILL、并发上限都由插件决定。应用 id 必须与注册表一一对应，否则整次派发被拒绝。
 - **日志一律以绝对路径交给子 Agent。** 附件和本机文件直接传路径；消息里的对象存储下载链接由派发工具下载（只允许白名单域名，不带鉴权，限制大小与耗时）。日志包不解压，由应用的日志分析 SKILL 在运行目录里解压。
-- **应用目录随时最新。** 每次加载 `/guanxiang` 都先 `git fetch` 各仓库（间隔由 `fetchIntervalMs` 控制，默认每次），再从远端分支最新提交的 git 对象读取应用描述生成应用目录。fetch 不改动任何检出，所以正在进行的分析不会挡住更新。最多等待 `refreshWaitMs`，超时就先用已有的目录，fetch 在后台继续。
-- **代码快照不可变。** 子 Agent 在 `<reposDir>/.snapshots/<仓库名>/` 下按提交创建的 `git worktree` 快照里工作。快照创建后不再改动，同一提交的派发共用一份；没有分析在用、且已不是最新提交的快照会被删除。
+- **应用目录随时最新。** 每次加载 `/guanxiang` 都先经 dsh-repo `git fetch` 各仓库（间隔由 `fetchIntervalMs` 控制，默认每次），再从远端分支最新提交的 git 对象读取应用描述生成应用目录。fetch 不改动任何检出，所以正在进行的分析不会挡住更新。最多等待 `refreshWaitMs`，超时就先用已有的目录，fetch 在后台继续。
+- **代码快照不可变。** 子 Agent 在 dsh-repo 按提交创建的 `git worktree` 只读快照里工作。快照创建后不再改动，同一提交的派发共用一份；没有分析在用、且已不是最新提交的快照会被删除。
 - **运行目录。** 每次派发在父会话目录下创建 `.guanxiang/runs/<runId>/<序号>-<应用 id>/`，下载的日志放在这里，子 Agent 也只在这里写文件；应用仓库对子 Agent 只读。
 - **等待式派发。** 工具等待所有子 Agent 结束后一次返回，一条消息对应一张完整回复；超过派发超时或调用被取消时停止仍在运行的子 Agent。子会话中不提供派发工具。
 - **SKILL 改进（可选，默认关闭）。** 子 Agent 发现应用的日志分析 SKILL 有欠缺时，可以在运行目录写出修改提议；经用户授权后，观象经 [dsh-repo](https://github.com/modestoma/dsh-repo) 把它提交到应用仓库的新分支并创建合并请求（GitLab MR 或 GitHub PR），见 [SKILL 改进](#skill-改进)。
@@ -89,16 +89,10 @@ npm 发行包已包含构建产物；本地 `link:` 安装前必须先执行 `pn
 ```yaml
 - id: guanxiang
   config:
-    reposDir: ~/.dsh/guanxiang/repos   # 默认 $DSH_HOME/guanxiang/repos
     repos:
       - url: git@github.com:example/order-service.git
       - url: https://github.com/example/pay-service.git
         branch: release                # 可选，默认跟随远端默认分支
-    gitCredentials:                    # https 仓库的访问令牌，只写令牌名称，不写令牌值
-      - url: https://gitlab.example.com  # 地址前缀；其下的 https 仓库使用该令牌
-        alias: guanxiang               # 可选，面板显示的名称
-        username: oauth2               # 可选，默认 oauth2
-        tokenEnv: GITLAB_TOKEN         # DSH 凭据库中的令牌名称，也可以是同名环境变量
     fetchIntervalMs: 0                 # 加载 /guanxiang 时距上次拉取超过该时间的仓库先 fetch；0 = 每次
     maxAppsPerRequest: 4               # 单次派发的任务上限
     dispatchTimeoutMs: 1800000         # 等待全部子 Agent 的上限
@@ -107,7 +101,6 @@ npm 发行包已包含构建产物；本地 `link:` 安装前必须先执行 `pn
       maxBytes: 536870912
       timeoutMs: 600000
     subagentProvider: spawn            # 子 Agent 使用的 ctx.subagents provider
-    gitTimeoutMs: 600000               # 单条 git 命令的超时
     refreshWaitMs: 15000               # 加载 /guanxiang 时等待 fetch 的上限；0 = 不等待
     autoInvoke: true                   # 任务匹配已注册应用时模型可自行加载入口 SKILL；false = 只能输入 /guanxiang
     skillUpdates:                      # SKILL 改进，见下文
@@ -122,22 +115,19 @@ npm 发行包已包含构建产物；本地 `link:` 安装前必须先执行 `pn
     analyzeTokenRef: GUANXIANG_ANALYZE_TOKEN  # 接口访问令牌在 DSH 凭据库中的名称
 ```
 
-配置在加载时校验，不合法时插件加载失败。git 地址支持 https/http/ssh/git/file URL、`user@host:path` 和绝对路径，拉取时使用本机已有的 git 凭据（SSH key 或 credential helper），不会弹出交互式输入。
+配置在加载时校验，不合法时插件加载失败。git 地址支持 https/http/ssh/git/file URL、`user@host:path` 和绝对路径。
 
-### 访问令牌
+### 仓库拉取与访问令牌
 
-用 https 地址拉取 GitLab 等私有仓库时，可以配置个人访问令牌（GitLab 需要 `read_repository` 权限；[SKILL 改进](#skill-改进) 的提交改由 dsh-repo 的令牌完成，这里不需要写权限）：
+应用仓库由 [dsh-repo](https://github.com/modestoma/dsh-repo)（0.1.0-beta.3 及以上）拉取，观象自己不再运行 git，需要同时安装 dsh-repo；没有 dsh-repo 或版本过旧时仓库拉取失败，原因显示在设置面板。
 
-- **配置只写名称。** `gitCredentials` 的每一项把一个地址前缀（`https://主机[:端口][/路径]`）对应到一个令牌名称 `tokenEnv`；地址在前缀下的 https 仓库使用该令牌，多个前缀匹配时取路径最长的。ssh、`user@host:path` 和本地路径不受影响。
-- **令牌值在 DSH 凭据库。** 令牌通过 DSH 的 `ctx.credentials` 读取（默认组合加载的 `@deepseek-ai/dsh-credentials-local`，文件 `$DSH_HOME/.credentials.yaml`，仅本机用户可读），可以在设置面板的「访问令牌」分页保存，也可以设置同名环境变量或写进 `.env`。每次拉取都重新读取，更换令牌不用重启。面板接口只接受已保存的配置引用的名称，也从不返回令牌值。
-- **只交给 git。** 拉取时令牌经环境变量交给这一次的 git 进程，由只对该主机生效的凭据助手在服务器要求认证时提供，本机为该主机配置的其他凭据助手不参与；令牌不出现在命令行参数、`.git/config`、日志或模型上下文里。需要 git 2.31 及以上版本。
-- **缺失时明确报错。** 地址匹配了令牌配置但令牌未设置，或 DSH 组合没有凭据服务时，该仓库拉取失败，原因显示在设置面板。
+- **镜像与快照在 dsh-repo。** 仓库镜像在 dsh-repo 的 `mirror.dir`（默认 `$DSH_HOME/dsh-repo/mirrors`）下，只用来 fetch，不检出文件；git 超时用 dsh-repo 的 `mirror.gitTimeoutMs`。旧版本的 `reposDir`、`gitTimeoutMs` 配置项仍能加载但不再生效，旧拉取目录可以手动删除。
+- **访问令牌是 dsh-repo 的主机。** https 地址属于 dsh-repo 中某个主机时，拉取自动使用该主机的令牌（GitLab 用户名 `oauth2`）。主机可以写在 dsh-repo 的 `hosts` 中，也可以在观象面板「访问令牌」分页添加；令牌存入 DSH 凭据库，面板只显示是否已设置。ssh 地址、`user@host:path`、其他主机和本地路径使用本机已有的 git 凭据（SSH key 或 credential helper），不会弹出交互式输入。
+- **旧令牌自动迁移。** 旧版本 `gitCredentials`（cordis.yml 或面板）中的每个地址，在 dsh-repo 可用后会以同样的地址、别名和已存的令牌值添加为 dsh-repo 主机；已存在的地址跳过。迁移后可以从 cordis.yml 删除 `gitCredentials`，面板下次保存时会去掉它。
 
-凭据库文件只防其他系统用户。与 DSH 中的模型 API Key 一样，Agent 的命令以同一系统用户运行，文件权限不能把令牌与 Agent 隔离（见 `@deepseek-ai/dsh-credentials-local` 文档）；建议使用只读权限、设置过期时间的令牌。
+凭据库文件只防其他系统用户。与 DSH 中的模型 API Key 一样，Agent 的命令以同一系统用户运行，文件权限不能把令牌与 Agent 隔离（见 `@deepseek-ai/dsh-credentials-local` 文档）；建议使用权限最小、设置过期时间的令牌。
 
-子 Agent 的命令在 dsh 的文件沙箱中运行：仓库只读，只有父会话的项目目录可写，运行目录就在其中。Linux 的 bubblewrap 沙箱会把 `/tmp` 换成空的临时目录，所以 `reposDir` 不要放在 `/tmp` 下，否则子 Agent 的命令看不到仓库。
-
-拉取目录 `<reposDir>/<仓库名>` 只用来 fetch，新克隆不检出文件（旧版本留下的检出文件不再使用）。多个同时运行的 dsh 进程不要共用同一个 `reposDir`：进程启动后首次同步时会删除快照目录里的遗留快照。
+子 Agent 的命令在 dsh 的文件沙箱中运行：仓库只读，只有父会话的项目目录可写，运行目录就在其中。Linux 的 bubblewrap 沙箱会把 `/tmp` 换成空的临时目录，所以 dsh-repo 的 `mirror.dir` 不要放在 `/tmp` 下，否则子 Agent 的命令看不到仓库。
 
 ### 设置面板
 
@@ -146,12 +136,12 @@ DSH Web 左侧栏的「观象」入口打开整页设置面板：
 | 分页 | 内容 |
 |---|---|
 | 应用仓库 | git 地址列表（分支可选）、每个仓库的拉取状态、提交号、应用描述与不可用原因，单个或全部重新拉取 |
-| 访问令牌 | 填 GitLab 地址、令牌别名和令牌三项即可添加；用户名固定为 oauth2，凭据库键名自动分配（`GUANXIANG_GITLAB_TOKEN`、`GUANXIANG_GITLAB_TOKEN_2`……）。每行显示令牌是否已设置及来源，可替换或清除 |
+| 访问令牌 | dsh-repo 的主机列表：选 GitLab 或 GitHub，填地址、别名和令牌即可添加，立即生效。每行显示令牌是否已设置及来源，可替换或清除；面板添加的主机可以删除，dsh-repo cordis.yml 中的主机只能改令牌 |
 | 日志下载 | 允许下载的域名、单文件大小上限、下载超时 |
 | 分析接口 | [日志平台分析接口](#日志平台分析接口)的开关、访问令牌（只显示是否已设置）、飞书渠道是否就绪，以及调用地址与字段摘要 |
-| 高级 | 拉取目录、更新间隔、单次应用数上限、派发超时、SKILL 改进开关与提议上限，恢复 cordis.yml 配置 |
+| 高级 | 更新间隔、单次应用数上限、派发超时、SKILL 改进开关与提议上限，恢复 cordis.yml 配置 |
 
-面板保存的值写入 `$DSH_HOME/guanxiang/settings.json`（只保存与 cordis.yml 不同的字段），按与配置相同的规则校验；令牌值不在其中，存入 DSH 凭据库。面板接口 `/guanxiang/*` 使用 DSH 自己的登录与来源校验，写操作另做同源校验。
+面板保存的值写入 `$DSH_HOME/guanxiang/settings.json`（只保存与 cordis.yml 不同的字段），按与配置相同的规则校验；主机保存在 dsh-repo，令牌值存入 DSH 凭据库。面板接口 `/guanxiang/*` 使用 DSH 自己的登录与来源校验，写操作另做同源校验。
 
 ## 应用仓库约定
 
@@ -170,17 +160,17 @@ skill: log-analysis             # 对应 .dsh/skills/log-analysis/SKILL.md
 
 `.dsh/skills/<skill>/SKILL.md`：这个应用的日志分析流程（如何解压日志包、日志格式、代码结构、常见问题）。它不能设置 `user-invocable: false`，因为派发时用 `/<skill>` 加载。
 
-插件拉取仓库后检查这两个文件；缺失、不合法，或多个仓库声明同一个 id 时，相关应用不可用，原因显示在设置面板。应用描述和 SKILL 必须是普通文件，不能是符号链接。删除地址不会删除本地克隆，它的快照在没有分析使用后删除。
+插件拉取仓库后检查这两个文件；缺失、不合法，或多个仓库声明同一个 id 时，相关应用不可用，原因显示在设置面板。应用描述和 SKILL 必须是普通文件，不能是符号链接。删除地址不会删除 dsh-repo 的本地镜像。
 
 ## SKILL 改进
 
-开启 `skillUpdates.enabled`（设置面板「高级」→「SKILL 改进」）后，分析中发现的 SKILL 欠缺可以经用户授权后提交为合并请求。提交和创建合并请求经 [dsh-repo](https://github.com/modestoma/dsh-repo) 的 `dshRepos` 服务完成（需要 dsh-repo 0.1.0-beta.2 及以上）：需要同时安装 dsh-repo，并在它的 `hosts` 中配置应用仓库所在的主机和令牌；没有该服务或版本不符时工具报错。
+开启 `skillUpdates.enabled`（设置面板「高级」→「SKILL 改进」）后，分析中发现的 SKILL 欠缺可以经用户授权后提交为合并请求。提交和创建合并请求经 [dsh-repo](https://github.com/modestoma/dsh-repo) 的 `dshRepos` 服务完成：应用仓库所在的主机要在 dsh-repo 中配置令牌（dsh-repo 的 `hosts` 或面板「访问令牌」）；没有该服务或版本不符时工具报错。
 
 1. **子 Agent 写提议。** 子 Agent 的任务消息多出一节说明：把要改的文件从 `.dsh/skills/<skill>/` 复制到运行目录的 `skill-proposal/files/`（保持相对路径）后修改，理由写进 `skill-proposal/reason.md`。仓库对子 Agent 仍然只读。
 2. **派发结果标出提议。** 派发结束后，观象检查已完成任务的提议：只接受普通文件和受限的文件名、UTF-8 文本、文件数与大小上限，`SKILL.md` 不能设置 `user-invocable: false`。合格的提议在结果中给出改动行数，并在运行目录写出 `skill-proposal.diff`；不合格的给出原因。
 3. **父 Agent 展示并提交。** 入口 SKILL 让父 Agent 在汇总回复后附上改动和 diff，再调用 `guanxiang_propose_skill`（参数为任务的运行目录和一句话摘要）。只接受本次 DSH 运行中由同一会话派发过的任务；应用、仓库和分析时的提交取自派发记录。
 4. **请求授权。** 工具通过 DSH 的审批服务（`ctx.approval`，`@deepseek-ai/dsh-user-approval`）请求一次性授权，说明将提交的仓库、分支、目标分支、改动文件和理由。经 dsh_channels 使用时显示为飞书决策卡片，在 DSH Web 中显示为审批提示；观象与 dsh_channels 之间没有代码依赖。只有「允许」才提交；拒绝、撤回或没有可回答的界面时都不提交。会话的审批策略为 `never`（例如 DSH 的「完全访问」权限模式）时请求一律被拒绝，所以要在「询问」类权限模式下使用；DSH 组合没有审批服务时工具报错。
-5. **提交新分支并创建合并请求。** 观象进程（不是 Agent）经 `dshRepos` 以分析时的提交为起点建新分支 `guanxiang/skill-<应用 id>-<树对象前缀>`，提交 `.dsh/skills/<skill>/` 下有改动的文件，再创建合入跟踪分支的合并请求，返回它的链接。同一改动的分支已存在时不再请求授权，也不提交；等待授权期间分支被别人建出时同样不提交。从不提交到已有分支或默认分支，合并由仓库的评审流程决定；合并后下次 `/guanxiang` 拉取即生效。提交成功但合并请求创建失败时，工具返回分支和失败原因，可以在代码托管平台上手动创建。
+5. **提交新分支并创建合并请求。** 观象进程（不是 Agent）经 `dshRepos` 以分析时的提交为起点建新分支 `guanxiang/skill-<应用 id>-<改动摘要前缀>`，提交 `.dsh/skills/<skill>/` 下有改动的文件，再创建合入跟踪分支的合并请求，返回它的链接。同一改动的分支已存在时不再请求授权，也不提交；等待授权期间分支被别人建出时同样不提交。从不提交到已有分支或默认分支，合并由仓库的评审流程决定；合并后下次 `/guanxiang` 拉取即生效。提交成功但合并请求创建失败时，工具返回分支和失败原因，可以在代码托管平台上手动创建。
 
 注意：
 
@@ -274,10 +264,10 @@ pnpm check        # 类型检查（Host 与 Client）+ 单元测试 + 构建 +
 |---|---|
 | `src/index.ts` | Cordis 插件入口 |
 | `src/service.ts` | 生效设置、注册表、入口 SKILL 与派发工具的注册 |
-| `src/repos/` | git 拉取、访问令牌、应用描述校验、应用注册表 |
+| `src/repos/` | dsh-repo 服务查找、应用描述校验、应用注册表 |
 | `src/skill/entry.ts` | `/guanxiang` 入口 SKILL |
 | `src/dispatch/` | 派发工具、日志下载、子 Agent 首条消息 |
-| `src/skill-update/` | SKILL 修改提议的校验、提交、授权与推送 |
+| `src/skill-update/` | SKILL 修改提议的校验、diff、授权与提交 |
 | `src/analyze/` | 日志平台分析接口：请求校验、令牌、到 `feishuTopics` 的转换 |
 | `src/settings/` | 面板契约、覆盖文件、HTTP 路由 |
 | `src/client/` | 左侧栏入口与设置页面 |