dsh-logalyze 0.2.0-beta.6 → 0.2.0-beta.8

package/README.md

@@ -48,7 +48,7 @@
 用户：/logalyze 订单服务昨晚 21 点下单报 500，日志见附件
         │
         ▼
-入口 SKILL（意图识别）── 先 fetch 各仓库，应用目录由远端最新提交的 .dsh/logalyze.yaml 生成
+入口 SKILL（意图识别）── 先 fetch 各仓库，应用目录由远端最新提交的 .agents/logalyze.yaml 生成
         │  logalyze_dispatch({ tasks: [{ app, question, logs }] })
         ▼
 派发工具：校验应用 id → 下载 URL 日志 → 并行启动子 Agent，等待全部结束
@@ -57,14 +57,15 @@
 父 Agent 按应用分节汇总，涉及多个应用时给出跨应用的推演
 ```
 
-- **一个入口，两种触发。** 入口 SKILL 是 `/logalyze`，dsh 在 Web、TUI、ACP 以及经 dsh_channels 的飞书消息中都能识别它。有可用应用且 `autoInvoke` 开启（默认）时，模型也能自行加载：dsh 给顶层 Agent 的 skill 目录里，观象的描述会列出每个可用应用的名称、id、别名和日志特征（总长不超过 500 字，放不下的只计数），用户说「分析这份订单服务的日志」或贴出带 `OrderController` 的报错时，模型会先加载观象。日志明显不属于任何已注册应用时，入口 SKILL 让模型按普通方式处理，不派发也不追问。子 Agent 的工作目录在 dsh-repo 的镜像目录内，那里不列出观象。应用增删时 dsh 会追加一条新的 skill 目录消息；想要确定触发时仍用 `/logalyze`。
+- **一个入口，两种触发。** 入口 SKILL 是 `/logalyze`，dsh 在 Web、TUI、ACP 以及经 dsh_channels 的飞书消息中都能识别它。有可用应用且 `autoInvoke` 开启（默认）时，模型也能自行加载：dsh 给顶层 Agent 的 skill 目录里，观象的描述会列出每个可用应用的名称、id、别名和日志特征（总长不超过 500 字，放不下的只计数），用户说「分析这份订单服务的日志」或贴出带 `OrderController` 的报错时，模型会先加载观象。日志明显不属于任何已注册应用时，入口 SKILL 让模型按普通方式处理，不派发也不追问。子 Agent 的工作目录在 `dshRepos` 服务的镜像目录内，那里不列出观象。应用增删时 dsh 会追加一条新的 skill 目录消息；想要确定触发时仍用 `/logalyze`。
 - **派发由代码完成。** 模型只给出应用 id、问题和日志位置；仓库目录、应用 SKILL、并发上限都由插件决定。应用 id 必须与注册表一一对应，否则整次派发被拒绝。
 - **日志一律以绝对路径交给子 Agent。** 附件和本机文件直接传路径；消息里的对象存储下载链接由派发工具下载（只允许白名单域名，不带鉴权，限制大小与耗时）。日志包不解压，由应用的日志分析 SKILL 在运行目录里解压。
-- **应用目录随时最新。** 每次加载 `/logalyze` 都先经 dsh-repo `git fetch` 各仓库（间隔由 `fetchIntervalMs` 控制，默认每次），再从远端分支最新提交的 git 对象读取应用描述生成应用目录。fetch 不改动任何检出，所以正在进行的分析不会挡住更新。最多等待 `refreshWaitMs`，超时就先用已有的目录，fetch 在后台继续。
-- **代码快照不可变。** 子 Agent 在 dsh-repo 按提交创建的 `git worktree` 只读快照里工作。快照创建后不再改动，同一提交的派发共用一份；没有分析在用、且已不是最新提交的快照会被删除。
+- **应用目录随时最新。** 每次加载 `/logalyze` 都先经 `dshRepos` 服务 fetch 各仓库（间隔由 `fetchIntervalMs` 控制，默认每次），再从远端分支最新提交的 git 对象读取应用描述生成应用目录。fetch 不改动任何检出，所以正在进行的分析不会挡住更新。最多等待 `refreshWaitMs`，超时就先用已有的目录，fetch 在后台继续。
+- **代码快照不可变。** 子 Agent 在 `dshRepos` 服务按提交创建的只读快照里工作，派发期间持有快照，结束后释放。
 - **运行目录。** 每次派发在父会话目录下创建 `.logalyze/runs/<runId>/<序号>-<应用 id>/`，下载的日志放在这里，子 Agent 也只在这里写文件；应用仓库对子 Agent 只读。
 - **等待式派发。** 工具等待所有子 Agent 结束后一次返回，一条消息对应一张完整回复；超过派发超时或调用被取消时停止仍在运行的子 Agent。子会话中不提供派发工具。
-- **SKILL 改进（可选，默认关闭）。** 子 Agent 发现应用的日志分析 SKILL 有欠缺时，可以在运行目录写出修改提议；经用户授权后，观象经 [dsh-repo](https://github.com/modestoma/dsh-repo) 把它提交到应用仓库的新分支并创建合并请求（GitLab MR 或 GitHub PR），见 [SKILL 改进](#skill-改进)。
+- **在对话中接入仓库。** 用户给出 git 地址时，模型可以经用户授权把它加入应用仓库列表；仓库缺少应用描述或 SKILL 时，派一个子 Agent 读代码起草，经授权后经 `dshRepos` 服务提交为合并请求，见[在对话中接入仓库](#在对话中接入仓库)。
+- **SKILL 改进（默认开启）。** 子 Agent 觉得应用的日志分析 SKILL 没能支撑这次分析，或用户指出 SKILL 的记录有误、要求改进时，父 Agent 询问用户是否改进；用户同意后由改进子 Agent 修改 SKILL 并把问题整理为 `cases/` 下的案例，观象经 `dshRepos` 服务提交到应用仓库的新分支并创建合并请求（GitLab MR 或 GitHub PR）供评审，见 [SKILL 改进](#skill-改进)。
 
 ## 安装与配置
 
@@ -104,10 +105,10 @@ npm 发行包已包含构建产物；本地 `link:` 安装前必须先执行 `pn
     refreshWaitMs: 15000               # 加载 /logalyze 时等待 fetch 的上限；0 = 不等待
     autoInvoke: true                   # 任务匹配已注册应用时模型可自行加载入口 SKILL；false = 只能输入 /logalyze
     skillUpdates:                      # SKILL 改进，见下文
-      enabled: false                   # 默认关闭
-      maxFiles: 16                     # 一次提议最多新增或修改的文件数
-      maxFileBytes: 262144             # 提议中单个文件的大小上限
-    skillUpdateAuthor:                 # 可选：SKILL 改进提交的作者；省略时是 dsh-repo 中该主机令牌的主人
+      enabled: true                    # 默认开启；false = 子 Agent 不记录 SKILL 不足，也不询问
+      maxFiles: 16                     # 一次改进最多新增或修改的文件数
+      maxFileBytes: 262144             # 改进中单个文件和 SKILL 不足记录的大小上限
+    skillUpdateAuthor:                 # 可选：SKILL 改进提交的作者；省略时是该主机令牌的主人
       name: 观象
       email: logalyze@example.com
     analyze:                           # 日志平台分析接口，见下文
@@ -117,16 +118,13 @@ npm 发行包已包含构建产物；本地 `link:` 安装前必须先执行 `pn
 
 配置在加载时校验，不合法时插件加载失败。git 地址支持 https/http/ssh/git/file URL、`user@host:path` 和绝对路径。
 
-### 仓库拉取与访问令牌
-
-应用仓库由 [dsh-repo](https://github.com/modestoma/dsh-repo) 拉取，观象自己不运行 git，需要同时安装 dsh-repo 0.1.0-beta.4 或更新版本；没有 dsh-repo 或其服务版本不兼容时仓库拉取失败，原因显示在设置面板。
+### 仓库拉取
 
-- **镜像与快照在 dsh-repo。** 仓库镜像在 dsh-repo 的 `mirror.dir`（默认 `$DSH_HOME/dsh-repo/mirrors`）下，只用来 fetch，不检出文件；git 超时用 dsh-repo 的 `mirror.gitTimeoutMs`。
-- **访问令牌是 dsh-repo 的主机。** https 地址属于 dsh-repo 中某个主机时，拉取自动使用该主机的令牌（GitLab 用户名 `oauth2`）。主机可以写在 dsh-repo 的 `hosts` 中，也可以在 DSH Web「插件 → dsh-repo」页面添加（观象面板「应用仓库」分页的「管理主机与令牌」直接跳过去）；令牌存入 DSH 凭据库。dsh-repo 中的主机或令牌每次变更后，观象自动重新拉取全部仓库。ssh 地址、`user@host:path`、其他主机和本地路径使用本机已有的 git 凭据（SSH key 或 credential helper），不会弹出交互式输入。
+观象自己不运行 git，也不依赖其他插件的包。拉取镜像、读取提交、创建只读快照和提交 SKILL 修改都调用运行时的 `dshRepos` 服务（服务版本 1，例如由 [dsh-repo](https://github.com/modestoma/dsh-repo) 提供），它用到的方法见 `src/repos/contract.ts`。没有该服务或服务版本不符时仓库拉取失败，原因显示在设置面板。
 
-凭据库文件只防其他系统用户。与 DSH 中的模型 API Key 一样，Agent 的命令以同一系统用户运行，文件权限不能把令牌与 Agent 隔离（见 `@deepseek-ai/dsh-credentials-local` 文档）；建议使用权限最小、设置过期时间的令牌。
+主机、访问令牌和镜像目录都在提供 `dshRepos` 的插件中配置；观象面板「应用仓库」分页的「管理主机与令牌」跳到 dsh-repo 的设置页。该服务报告主机或令牌变更后，观象自动重新拉取全部仓库。
 
-子 Agent 的命令在 dsh 的文件沙箱中运行：仓库只读，只有父会话的项目目录可写，运行目录就在其中。Linux 的 bubblewrap 沙箱会把 `/tmp` 换成空的临时目录，所以 dsh-repo 的 `mirror.dir` 不要放在 `/tmp` 下，否则子 Agent 的命令看不到仓库。
+子 Agent 的命令在 dsh 的文件沙箱中运行：仓库只读，只有父会话的项目目录可写，运行目录就在其中。Linux 的 bubblewrap 沙箱会把 `/tmp` 换成空的临时目录，所以镜像目录不要放在 `/tmp` 下，否则子 Agent 的命令看不到仓库。
 
 ### 设置面板
 
@@ -137,7 +135,7 @@ DSH Web 左侧栏的「观象」入口打开整页设置面板：
 | 应用仓库 | git 地址列表（分支可选）、每个仓库的拉取状态、提交号、应用描述与不可用原因，单个或全部重新拉取，以及跳转到 dsh-repo 主机与令牌设置的按钮 |
 | 日志下载 | 允许下载的域名、单文件大小上限、下载超时 |
 | 分析接口 | [日志平台分析接口](#日志平台分析接口)的开关、访问令牌（只显示是否已设置）、飞书渠道是否就绪，以及调用地址与字段摘要 |
-| 高级 | 更新间隔、单次应用数上限、派发超时、SKILL 改进开关与提议上限，恢复 cordis.yml 配置 |
+| 高级 | 更新间隔、单次应用数上限、派发超时、SKILL 改进开关与文件上限，恢复 cordis.yml 配置 |
 
 面板保存的值写入 `$DSH_HOME/logalyze/settings.json`（只保存与 cordis.yml 不同的字段），按与配置相同的规则校验；分析接口令牌存入 DSH 凭据库。面板接口 `/logalyze/*` 使用 DSH 自己的登录与来源校验，写操作另做同源校验。
 
@@ -145,7 +143,7 @@ DSH Web 左侧栏的「观象」入口打开整页设置面板：
 
 每个应用仓库需要两样东西（完整示例见 [examples/order-service](examples/order-service)，接入步骤与 SKILL 写作要点见[应用仓库接入指南](docs/app-repo-guide.md)）：
 
-`.dsh/logalyze.yaml` 应用描述：
+`.agents/logalyze.yaml` 应用描述：
 
 ```yaml
 id: order-service               # 小写短横线格式，派发与分析请求按它对应应用
@@ -153,29 +151,46 @@ name: 订单服务                   # 显示名，也是子 Agent 的标签
 description: 下单、库存扣减与支付回调
 aliases: [订单, 下单, order]     # 用户对它的其他叫法
 logHints: [order-service, OrderController]   # 能识别本应用日志的字符串
-skill: log-analysis             # 对应 .dsh/skills/log-analysis/SKILL.md
+skill: log-analysis             # 对应 .agents/skills/log-analysis/SKILL.md
 ```
 
-`.dsh/skills/<skill>/SKILL.md`：这个应用的日志分析流程（如何解压日志包、日志格式、代码结构、常见问题）。它不能设置 `user-invocable: false`，因为派发时用 `/<skill>` 加载。
+`.agents/skills/<skill>/SKILL.md`：这个应用的日志分析流程（如何解压日志包、日志格式、代码结构、常见问题）。它不能设置 `user-invocable: false`，因为派发时用 `/<skill>` 加载。
 
-插件拉取仓库后检查这两个文件；缺失、不合法，或多个仓库声明同一个 id 时，相关应用不可用，原因显示在设置面板。应用描述和 SKILL 必须是普通文件，不能是符号链接。删除地址不会删除 dsh-repo 的本地镜像。
+插件拉取仓库后检查这两个文件；缺失、不合法，或多个仓库声明同一个 id 时，相关应用不可用，原因显示在设置面板。应用描述和 SKILL 必须是普通文件，不能是符号链接。DSH 也从 `.dsh/skills/` 加载项目 SKILL，并且同名时它优先，所以应用仓库不要在 `.dsh/skills/` 下留同名的 SKILL。删除地址不会删除本地镜像。
 
 ## SKILL 改进
 
-开启 `skillUpdates.enabled`（设置面板「高级」→「SKILL 改进」）后，分析中发现的 SKILL 欠缺可以经用户授权后提交为合并请求。提交和创建合并请求经 [dsh-repo](https://github.com/modestoma/dsh-repo) 的 `dshRepos` 服务完成：应用仓库所在的主机要在 dsh-repo 中配置令牌（dsh-repo 的 `hosts` 或「插件 → dsh-repo」页面）；没有该服务或版本不符时工具报错。
+`skillUpdates.enabled` 默认开启（设置面板「高级」→「SKILL 改进」可以关闭）。分析中 SKILL 没覆盖到的问题，以及用户指出的 SKILL 错误，经用户同意后沉淀为 SKILL 修改和案例，以合并请求的形式交给仓库维护者评审。改进有两个来源：分析子 Agent 记录的不足，和用户的反馈。提交和创建合并请求经 `dshRepos` 服务完成，应用仓库所在的主机要在提供该服务的插件中配置令牌；没有该服务或版本不符时工具报错。
+
+1. **分析子 Agent 记录不足。** 子 Agent 的任务消息多出一节说明：分析完成后，如果 SKILL 没能很好地支撑这次分析（日志格式描述不对、缺少这类故障的排查方法或排除规则、代码路径过时、靠自己摸索才找到根因），就在运行目录写 `skill-gap.md`，记下 SKILL 哪里不足、实际怎样定位、关键日志行（去掉具体数据）和代码位置。子 Agent 不修改 SKILL，SKILL 足够时不写这个文件。
+2. **派发结果标出不足。** 派发结束后，观象检查已完成任务的记录（普通文件、UTF-8 文本、大小不超过 `maxFileBytes`），在结果中标出「SKILL 不足」和记录摘要。观象记住本次 DSH 运行中每个已完成的派发任务，供之后的改进引用。
+3. **用户也可以主动要求。** 分析按 SKILL 已有的记录走了，用户事后指出那条记录有错；或者在新会话里直接说「优化一下订单服务的日志分析 SKILL」。这时顶层 Agent 先用 `logalyze_show_skill` 读出现有 SKILL（最新同步提交中的文件列表和某个文件，默认 `SKILL.md`，只读），对照着和用户确认哪部分不对、正确做法是什么、有没有样例日志，问清后再进入下一步。改进子 Agent 不能和用户对话，所以讨论放在询问之前。
+4. **询问用户。** 顶层 Agent 调用 `logalyze_improve_skill`。参数是 `workDir`（本会话一次已完成的派发任务）或 `app`（没有分析时）二选一，加上 `feedback`（用户的纠正，尽量保留原话）和可选的 `logs`；没有不足记录时 `feedback` 必填。工具经 DSH 的审批服务（`ctx.approval`，`@deepseek-ai/dsh-user-approval`）问一次「是否改进 SKILL」，说明不足摘要或用户反馈、仓库和目标分支。经 dsh_channels 使用时显示为飞书决策卡片，在 DSH Web 中显示为审批提示；观象与 dsh_channels 之间没有代码依赖。只有「允许」才继续；拒绝、撤回或没有可回答的界面时不起草也不提交。会话的审批策略为 `never`（例如 DSH 的「完全访问」权限模式）时请求一律被拒绝，所以要在「询问」类权限模式下使用；DSH 组合没有审批服务时工具报错。
+5. **改进子 Agent 起草。** 用户同意后，观象在应用最新提交的只读快照里启动一个改进子 Agent，首行用 `/logalyze-improve` 加载观象自带的改进指南。任务消息给出改进的依据：有分析时是分析时的问题、结论、`skill-gap.md`（如果有）和日志，有反馈时是用户反馈（与现有内容冲突时以用户反馈为准，并对照代码核实），以及附带的样例日志。它把修改写到运行目录下的 `improve-<序号>/skill-proposal/files/`（对应 `.agents/skills/<skill>/`；有分析时在该任务的运行目录下，否则在新的 `.logalyze/runs/<runId>/` 下），包括对 `SKILL.md` 或 `references/` 的修改、案例 `cases/<日期>-<slug>.md`（现象、脱敏的日志特征、根因、定位路径、确认与排除、本次 SKILL 改进），以及 `SKILL.md` 中「案例索引」表的一行；改动说明写进 `skill-proposal/reason.md`，第一行是标题。等待上限是 `dispatchTimeoutMs`。
+6. **检查并提交。** 观象检查修改：只接受普通文件和受限的文件名、UTF-8 文本、文件数与大小上限；依据一次分析时必须新增或修改 `cases/` 下的一份案例，只依据用户反馈时案例可选；`SKILL.md` 的 frontmatter `name` 不能变，也不能设置 `user-invocable: false`。合格后在运行目录写出 `skill-proposal.diff`，由观象进程（不是 Agent）经 `dshRepos` 以快照的提交为起点建新分支 `logalyze/skill-<应用 id>-<改动摘要前缀>`，提交 `.agents/skills/<skill>/` 下有改动的文件，再创建合入跟踪分支的合并请求。用户在第 4 步已经同意，这一步不再询问。工具返回改动文件、改进子 Agent 的改动说明和合并请求链接，父 Agent 转告用户，评审在合并请求中进行。修改不合格或子 Agent 没有完成时工具返回原因，不提交，可以再试一次；同一改动的分支已存在时不提交；提交成功但合并请求创建失败时返回分支和失败原因，可以在代码托管平台上手动创建。从不提交到已有分支或默认分支，合并后下次 `/logalyze` 拉取即生效。
 
-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，再调用 `logalyze_propose_skill`（参数为任务的运行目录和一句话摘要）。只接受本次 DSH 运行中由同一会话派发过的任务；应用、仓库和分析时的提交取自派发记录。
-4. **请求授权。** 工具通过 DSH 的审批服务（`ctx.approval`，`@deepseek-ai/dsh-user-approval`）请求一次性授权，说明将提交的仓库、分支、目标分支、改动文件和理由。经 dsh_channels 使用时显示为飞书决策卡片，在 DSH Web 中显示为审批提示；观象与 dsh_channels 之间没有代码依赖。只有「允许」才提交；拒绝、撤回或没有可回答的界面时都不提交。会话的审批策略为 `never`（例如 DSH 的「完全访问」权限模式）时请求一律被拒绝，所以要在「询问」类权限模式下使用；DSH 组合没有审批服务时工具报错。
-5. **提交新分支并创建合并请求。** 观象进程（不是 Agent）经 `dshRepos` 以分析时的提交为起点建新分支 `logalyze/skill-<应用 id>-<改动摘要前缀>`，提交 `.dsh/skills/<skill>/` 下有改动的文件，再创建合入跟踪分支的合并请求，返回它的链接。同一改动的分支已存在时不再请求授权，也不提交；等待授权期间分支被别人建出时同样不提交。从不提交到已有分支或默认分支，合并由仓库的评审流程决定；合并后下次 `/logalyze` 拉取即生效。提交成功但合并请求创建失败时，工具返回分支和失败原因，可以在代码托管平台上手动创建。
+**改进指南 `/logalyze-improve`。** 正文在包内的 [skills/logalyze-improve/SKILL.md](skills/logalyze-improve/SKILL.md)，写明怎样判断缺口类型、案例模板与脱敏规则、哪些知识补进 `SKILL.md` 或 `references/`、怎样维护「案例索引」，以及改动说明的格式。和接入套件一样在任何目录都列出，只能由用户输入或首行手势加载；开发者也可以在自己的仓库里输入 `/logalyze-improve`，手动把一次排查沉淀为案例。
 
 注意：
 
-- 支持 GitLab（包括自建实例）和 GitHub。应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 dsh-repo 识别为已配置主机上的仓库；dsh-repo 的令牌在 GitLab 上需要 `api` 权限，在 GitHub 上需要 Contents 和 Pull requests 的读写权限。
-- 有写权限的令牌可以改动它能访问的所有项目。建议用只覆盖应用仓库的项目或组访问令牌，设置过期时间，用 dsh-repo 的 `repos` 限定范围，并保护应用仓库的默认分支。
-- 合并请求以 dsh-repo 令牌主人的身份创建，提交作者是 `skillUpdateAuthor`，省略时也是令牌主人。飞书群里点「允许」的人可能不是令牌主人；合并请求描述写明了来源会话与分析提交。
-- 日志内容不可信，可能诱导模型写出不当的 SKILL。观象只限制改动范围，内容需要授权的人和合并请求的评审者把关。
+- 支持 GitLab（包括自建实例）和 GitHub。应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 `dshRepos` 识别为已配置主机上的仓库；该主机的令牌在 GitLab 上需要 `api` 权限，在 GitHub 上需要 Contents 和 Pull requests 的读写权限。
+- 有写权限的令牌可以改动它能访问的所有项目。建议用只覆盖应用仓库的项目或组访问令牌，设置过期时间，并保护应用仓库的默认分支。
+- 合并请求以该主机令牌主人的身份创建，提交作者是 `skillUpdateAuthor`，省略时也是令牌主人。飞书群里点「允许」的人可能不是令牌主人；合并请求描述写明了来源会话与分析提交。
+- 日志内容不可信，可能诱导模型写出不当的 SKILL 或在案例里留下未脱敏的数据。观象只限制改动范围，内容需要合并请求的评审者把关。
+
+## 在对话中接入仓库
+
+除了在设置面板添加，用户也可以在对话里说「把 git@gitlab.example.com:shop/order.git 接入观象」。顶层 Agent 有三个工具，子会话中都不提供：
+
+| 工具 | 何时提供 | 做什么 |
+|---|---|---|
+| `logalyze_add_repo` | 总是 | 参数为 git 地址和可选分支。经用户一次性授权后写入与面板相同的 `settings.json`，等待第一次拉取结束，返回应用可用、需要起草或拉取失败的原因。地址已在列表中时不请求授权，只重新拉取 |
+| `logalyze_init_repo` | 有仓库已拉取但缺少应用描述或 SKILL 时 | 参数为 git 地址、可选的用户说明和样例日志（`path` 或白名单内的 `url`）。在最新提交的只读快照里启动一个起草子 Agent，首行用 `/logalyze-kit` 加载接入套件，把 `logalyze.yaml` 和一个日志分析 SKILL（大型仓库按领域拆到 `references/`）写到运行目录 `.logalyze/runs/<runId>/init/repo-init/`，结束后检查初稿并写出 `repo-init.diff`，不提交 |
+| `logalyze_submit_init` | 本会话有起草结果时 | 参数为起草的运行目录。重新检查初稿，经用户一次性授权后以起草时的提交为起点建新分支 `logalyze/init-<应用 id>-<改动摘要前缀>`，提交 `.agents/` 下有改动的文件，并创建合入跟踪分支的合并请求 |
+
+**接入套件 `/logalyze-kit`。** 观象自带一个 SKILL，写明怎样为应用仓库编写应用描述和日志分析 SKILL：从代码和日志配置里找什么、`logalyze.yaml` 字段、SKILL.md 与 `references/` 的结构模板、约束和自检清单。正文在包内的 [skills/logalyze-kit/SKILL.md](skills/logalyze-kit/SKILL.md)，插件加载时读取，缺失或不合法时加载失败。它在任何目录都列出（包括子 Agent 所在的仓库快照），只能由用户输入或首行手势加载，模型不会自行选用。开发者也可以在自己的仓库里运行 dsh，输入 `/logalyze-kit` 直接编写或改进 SKILL。
+
+初稿的检查规则与拉取时相同：`logalyze.yaml` 合法，SKILL 存在、frontmatter 的 `name` 等于 `skill` 字段、不设置 `user-invocable: false`，应用 id 不与其他仓库重复；初稿只能包含 `logalyze.yaml` 和它指定的 `skills/<skill>/` 下的文件，文件数和大小上限沿用 `skillUpdates.maxFiles` 与 `maxFileBytes`（关闭 SKILL 改进时同样生效）。起草子 Agent 的等待上限是 `dispatchTimeoutMs`。授权方式、令牌权限、提交作者（`skillUpdateAuthor`）和合并请求的规则与 [SKILL 改进](#skill-改进) 相同；合并后下一次 `/logalyze` 拉取即启用该应用。用户拒绝提交时，初稿文件仍在运行目录中，可以手动提交。
 
 ## 日志平台分析接口
 
@@ -257,11 +272,14 @@ pnpm check        # 类型检查（Host 与 Client）+ 单元测试 + 构建 +
 | 路径 | 内容 |
 |---|---|
 | `src/index.ts` | Cordis 插件入口 |
-| `src/service.ts` | 生效设置、注册表、入口 SKILL 与派发工具的注册 |
-| `src/repos/` | dsh-repo 服务查找、应用描述校验、应用注册表 |
-| `src/skill/entry.ts` | `/logalyze` 入口 SKILL |
-| `src/dispatch/` | 派发工具、日志下载、子 Agent 首条消息 |
-| `src/skill-update/` | SKILL 修改提议的校验、diff、授权与提交 |
+| `src/service.ts` | 生效设置、注册表、入口 SKILL 与各工具的注册 |
+| `src/repos/` | `dshRepos` 服务需求与查找、应用描述校验、应用注册表 |
+| `src/skill/` | `/logalyze` 入口 SKILL 与随包指导 SKILL（`/logalyze-kit`、`/logalyze-improve`）的 provider |
+| `skills/logalyze-kit/` | 接入套件 SKILL 正文 |
+| `skills/logalyze-improve/` | SKILL 改进指南正文 |
+| `src/dispatch/` | 派发工具、日志下载、子 Agent 首条消息与运行 |
+| `src/skill-update/` | SKILL 查看工具、SKILL 不足记录、改进工具与改进子 Agent 首条消息、修改校验、diff 与提交 |
+| `src/onboard/` | 在对话中添加仓库、起草应用描述与 SKILL、提交接入合并请求 |
 | `src/analyze/` | 日志平台分析接口：请求校验、令牌、到 `feishuTopics` 的转换 |
 | `src/settings/` | 面板契约、覆盖文件、HTTP 路由 |
 | `src/client/` | 左侧栏入口与设置页面 |

package/docs/app-repo-guide.md

@@ -8,16 +8,16 @@
 
 | 谁 | 做什么 |
 |---|---|
-| 应用仓库 | 提供应用描述 `.dsh/logalyze.yaml` 和日志分析 SKILL `.dsh/skills/<skill>/SKILL.md`，推送到观象跟踪的分支 |
-| 观象部署方 | 同时安装观象和 [dsh-repo](https://github.com/modestoma/dsh-repo)，在 DSH Web 左侧栏的「观象」设置面板里填 git 地址，按需配置访问令牌、日志下载白名单和 SKILL 改进 |
-| 观象插件 | 经 dsh-repo 拉取仓库、生成应用目录、下载日志、在应用代码的只读快照里启动子 Agent，并汇总各应用的结论 |
+| 应用仓库 | 提供应用描述 `.agents/logalyze.yaml` 和日志分析 SKILL `.agents/skills/<skill>/SKILL.md`，推送到观象跟踪的分支 |
+| 观象部署方 | 同时安装观象和提供 `dshRepos` 服务的插件（如 [dsh-repo](https://github.com/modestoma/dsh-repo)），在 DSH Web 左侧栏的「观象」设置面板里填 git 地址，按需配置日志下载白名单和 SKILL 改进；主机和访问令牌在 dsh-repo 中配置 |
+| 观象插件 | 经 `dshRepos` 服务拉取仓库、生成应用目录、下载日志、在应用代码的只读快照里启动子 Agent，并汇总各应用的结论 |
 
 ## 接入清单
 
-1. 在仓库里新增 `.dsh/logalyze.yaml`，见[应用描述](#应用描述)。
-2. 在仓库里新增 `.dsh/skills/<skill>/SKILL.md`，见[日志分析 SKILL](#日志分析-skill)。
+1. 在仓库里新增 `.agents/logalyze.yaml`，见[应用描述](#应用描述)。也可以在仓库里运行装有观象的 dsh，输入 `/logalyze-kit`，让模型按观象自带的接入套件起草这一步和下一步的文件。
+2. 在仓库里新增 `.agents/skills/<skill>/SKILL.md`，见[日志分析 SKILL](#日志分析-skill)。
 3. 把这两个文件推送到观象跟踪的分支（默认是远端默认分支）。观象读取的是远端最新提交，不读任何本地检出。
-4. 在设置面板「应用仓库」中添加 git 地址；https 私有仓库另在「访问令牌」中为它所在的主机配置令牌，见[在设置面板接入](#在设置面板接入)。
+4. 在设置面板「应用仓库」中添加 git 地址，或在对话中让观象添加（见[在对话中接入](#在对话中接入)）；https 私有仓库另在 dsh-repo 中为它所在的主机配置令牌，见[在设置面板接入](#在设置面板接入)。
 5. 日志以对象存储链接提供时，在「日志下载」中加入该域名。
 6. 面板中该仓库显示为可用后，发一条 `/logalyze <问题>`，附上日志试跑。
 
@@ -25,7 +25,7 @@
 
 ```
 order-service/
-├── .dsh/
+├── .agents/
 │   ├── logalyze.yaml
 │   └── skills/
 │       └── log-analysis/
@@ -33,7 +33,7 @@ order-service/
 └── src/ …
 ```
 
-`.dsh/logalyze.yaml`：
+`.agents/logalyze.yaml`：
 
 ```yaml
 id: order-service
@@ -44,7 +44,7 @@ logHints: [order-service, OrderController]
 skill: log-analysis
 ```
 
-`.dsh/skills/log-analysis/SKILL.md`：
+`.agents/skills/log-analysis/SKILL.md`：
 
 ```markdown
 ---
@@ -74,7 +74,7 @@ description: 订单服务的日志分析流程：解压日志包、定位异常
 
 ## 应用描述
 
-`.dsh/logalyze.yaml` 放在仓库根目录下，必须是普通文件（不能是符号链接）。
+`.agents/logalyze.yaml` 放在仓库根目录下，必须是普通文件（不能是符号链接）。
 
 | 字段 | 必填 | 说明 |
 |---|---|---|
@@ -83,11 +83,11 @@ description: 订单服务的日志分析流程：解压日志包、定位异常
 | `description` | 是 | 一句话说明应用负责什么，出现在入口 SKILL 的应用目录里 |
 | `aliases` | 否 | 用户对这个应用的其他叫法，如中文名简称、英文名 |
 | `logHints` | 否 | 能从日志里认出本应用的字符串，如服务名、主类名、日志 tag |
-| `skill` | 是 | 日志分析 SKILL 名，小写短横线格式；对应 `.dsh/skills/<skill>/SKILL.md` |
+| `skill` | 是 | 日志分析 SKILL 名，小写短横线格式；对应 `.agents/skills/<skill>/SKILL.md` |
 
 规则：
 
-- 观象每次加载 `/logalyze` 时先经 dsh-repo `git fetch`，再从跟踪分支的最新提交读取应用描述。改了描述或 SKILL，推送后下一次 `/logalyze` 就生效，不用重启。
+- 观象每次加载 `/logalyze` 时先经 `dshRepos` 服务 fetch，再从跟踪分支的最新提交读取应用描述。改了描述或 SKILL，推送后下一次 `/logalyze` 就生效，不用重启。
 - 一个仓库对应一个应用。多个仓库声明同一个 `id` 时，这几个仓库全部不可用。
 - 描述不合法、SKILL 缺失或设置了 `user-invocable: false` 时，应用不可用，原因显示在设置面板。
 
@@ -95,7 +95,7 @@ description: 订单服务的日志分析流程：解压日志包、定位异常
 
 ### 硬性要求
 
-- 路径是 `.dsh/skills/<skill>/SKILL.md`，`<skill>` 与 `logalyze.yaml` 的 `skill` 字段相同，必须是普通文件。
+- 路径是 `.agents/skills/<skill>/SKILL.md`，`<skill>` 与 `logalyze.yaml` 的 `skill` 字段相同，必须是普通文件。
 - frontmatter 的 `name` 也要等于 `<skill>`。DSH 按 frontmatter 的 `name` 注册 SKILL，观象派发时用 `/<skill>` 加载它，名称不一致时子 Agent 加载不到。`description` 必填。
 - 不能设置 `user-invocable: false`，否则 `/<skill>` 无法加载，观象会把应用标为不可用。
 - 可以设置 `disable-model-invocation: true`：开发者在本仓库里使用 dsh 时模型就不会自行加载它，观象的 `/<skill>` 加载不受影响。
@@ -135,9 +135,31 @@ description: 订单服务的日志分析流程：解压日志包、定位异常
 - **不要依赖需要审批的操作。** 子 Agent 不会弹出审批或提问，通过飞书使用时 dsh_channels 也不转发子 Agent 的审批。联网下载、安装依赖、写运行目录以外的位置、启动服务或容器这类操作会直接失败。需要的工具（`tar`、`unzip`、`rg`、`jq` 等）要在运行 dsh 的机器上预先装好。
 - **先过滤再阅读。** 日志可能很大，先按时间、traceId、订单号等用 `grep`/`rg` 缩小范围，不要通读或整体复制。
 - **写清日志格式和代码地图。** 每行字段的含义、时间格式与时区、关键 logger 名对应的代码目录、调用链上的上下游服务。
-- **写已知故障和排除规则。** 比如「库存服务 503 属于下游问题」。这部分是 SKILL 最有价值的内容，也是 [SKILL 改进](#skill-改进可选) 最常补充的内容。
+- **写已知故障和排除规则。** 比如「库存服务 503 属于下游问题」。这部分是 SKILL 最有价值的内容，也是 [SKILL 改进](#skill-改进) 最常补充的内容。
 - **说明版本对不上时怎么办。** 子 Agent 看的是跟踪分支的最新代码，日志可能来自更早的版本。日志里打印了版本号或提交号时，告诉子 Agent 在哪里找，并在结论中说明版本差异。
 
+### 大型仓库：用 references 拆分领域
+
+工程较大、排查知识分属多个细分领域（如下单、支付回调、库存、定时任务）时，仍然只写一个日志分析 SKILL，把各领域的知识拆到它的 `references/` 下：
+
+```
+.agents/skills/order-logs/
+├── SKILL.md              # 公共部分 + 领域索引 + 案例索引
+├── references/
+│   ├── checkout.md       # 下单
+│   ├── payment.md        # 支付回调
+│   └── inventory.md      # 库存扣减
+└── cases/                # SKILL 改进沉淀的案例，一个问题一份
+    └── 2026-10-31-pay-callback-timeout.md
+```
+
+- `SKILL.md` 只写所有领域共用的内容：解压、日志格式、通用排查步骤，再加一张领域索引表，写明「问题或日志涉及什么 → 读哪份 references」，并要求子 Agent 先按索引选定领域再读对应文件，不要一次读完全部 references。
+- 每份 `references/<领域>.md` 写该领域的日志特征（logger 名、关键字段）、代码地图和已知故障与排除规则。
+- `cases/` 由 [SKILL 改进](#skill-改进) 维护：每份案例记录一次 SKILL 没覆盖到的问题，`SKILL.md` 末尾的「案例索引」表列出每份案例的关键特征，子 Agent 遇到相符的日志时再读对应案例。也可以手写案例，或在仓库里输入 `/logalyze-improve` 让 dsh 帮你整理。
+- 不要拆成多个 SKILL。观象只用 `/<skill>` 确定性地加载 `logalyze.yaml` 指定的这一个；其他 SKILL 要靠子 Agent 按 description 自行挑选，设置了 `disable-model-invocation: true` 的还无法加载。[SKILL 改进](#skill-改进) 也只能修改 `.agents/skills/<skill>/` 目录，放在其他 SKILL 里的知识不会被改进。
+
+references 适合同一个应用内的领域划分。几个领域其实是独立部署、各有日志、需要分别给结论的服务时，它们是不同的应用；目前一个仓库只能声明一个应用，见[应用描述](#应用描述)的规则。
+
 ## 让观象认出你的应用
 
 用户输入 `/logalyze` 时一定走观象。没有输入时，只要有可用应用且 `autoInvoke` 开启（默认开启），模型也会在任务匹配时自行加载观象，比如用户说「帮我看下订单服务的报错日志」，或贴出带 `OrderController` 的堆栈。应用描述决定匹配效果：
@@ -149,6 +171,18 @@ description: 订单服务的日志分析流程：解压日志包、定位异常
 
 日志明显不属于任何已注册应用时，模型按普通方式处理，不会派发。
 
+## 在对话中接入
+
+仓库还没有应用描述和 SKILL 时，可以让观象起草，省去前两步：
+
+1. 在 DSH 对话（Web 或飞书）中说「把 `<git 地址>` 接入观象」，可以附上样例日志，并说明模块划分或最常排查的问题。
+2. 观象请求授权后把地址加入应用仓库列表并拉取。仓库已有合法的描述和 SKILL 时直接可用。
+3. 缺少描述或 SKILL 时，观象派一个子 Agent 在仓库的只读快照里按接入套件 `/logalyze-kit` 读代码和样例日志，起草 `.agents/logalyze.yaml` 和日志分析 SKILL（大型仓库按[领域拆到 references](#大型仓库用-references-拆分领域)），并说明哪些内容是推断、需要你确认。
+4. 观象展示改动并请求授权；允许后提交到新分支 `logalyze/init-<应用 id>-…`，创建合入跟踪分支的合并请求。令牌权限要求与 [SKILL 改进](#skill-改进) 相同。
+5. 评审并修改合并请求，合并后下一次 `/logalyze` 即启用该应用。
+
+起草的 SKILL 是起点。日志格式、已知故障这些内容来自代码推断，合并前请对照真实日志核对，之后可以靠 SKILL 改进持续补充。
+
 ## 在设置面板接入
 
 DSH Web 左侧栏「观象」打开设置面板。面板保存的值写入 `$DSH_HOME/logalyze/settings.json`，也可以在 profile 的 cordis.yml 中按 `id: logalyze` 配置默认值（字段见 [README](../README.md#安装与配置)）。
@@ -156,17 +190,16 @@ DSH Web 左侧栏「观象」打开设置面板。面板保存的值写入 `$DSH
 | 分页 | 应用仓库需要的设置 |
 |---|---|
 | 应用仓库 | 填 git 地址，分支可选（默认跟随远端默认分支）。支持 https/http/ssh/git/file URL、`user@host:path` 和绝对路径。拉取后显示提交号、应用描述或不可用原因 |
-| 访问令牌 | https 私有仓库需要。这里管理的是 dsh-repo 的主机：选 GitLab 或 GitHub，填主机地址（如 `https://gitlab.example.com`）、别名和令牌即可添加，立即生效 |
 | 日志下载 | 日志以链接提供时，把对象存储域名加入白名单（同时允许其子域名） |
 | 高级 | 拉取间隔、单次应用数上限、派发超时、SKILL 改进开关 |
 
 ### git 地址与令牌
 
-- 仓库由 dsh-repo 拉取，观象自己不运行 git。没有安装 dsh-repo 或其服务版本不兼容时，所有仓库都拉取失败，原因显示在面板。
-- https 地址属于 dsh-repo 中某个主机时，拉取自动使用该主机的令牌（GitLab 用户名 `oauth2`）。主机可以在面板「访问令牌」添加，也可以写在 dsh-repo 的 `hosts` 配置中。令牌值存在 DSH 凭据库，不进配置文件、命令行和模型上下文。
+- 仓库由 `dshRepos` 服务拉取，观象自己不运行 git。没有该服务或服务版本不兼容时，所有仓库都拉取失败，原因显示在面板。
+- https 私有仓库所在主机的令牌在 dsh-repo 中配置，「应用仓库」分页的「管理主机与令牌」直接跳过去。主机或令牌变更后观象自动重新拉取全部仓库。
 - ssh 地址、`user@host:path`、其他主机和本地路径使用运行 dsh 的机器上已有的 git 凭据（SSH key 或 credential helper），不会弹出交互式输入。
-- 令牌权限：只拉取时，GitLab 需要 `read_repository`，GitHub 需要 Contents 读权限。开启 [SKILL 改进](#skill-改进可选) 时，GitLab 需要 `api`，GitHub 需要 Contents 和 Pull requests 读写权限。
-- **建议使用项目访问令牌**（或组访问令牌）：只覆盖要接入的应用仓库，设置过期时间，并用 dsh-repo 的 `repos` 限定范围。个人令牌能访问令牌主人有权限的所有项目，加了写权限后风险更大。
+- 令牌权限：只拉取时，GitLab 需要 `read_repository`，GitHub 需要 Contents 读权限。开启 [SKILL 改进](#skill-改进) 时，GitLab 需要 `api`，GitHub 需要 Contents 和 Pull requests 读写权限。
+- **建议使用项目访问令牌**（或组访问令牌）：只覆盖要接入的应用仓库，设置过期时间。个人令牌能访问令牌主人有权限的所有项目，加了写权限后风险更大。
 
 ### 日志下载
 
@@ -174,24 +207,33 @@ DSH Web 左侧栏「观象」打开设置面板。面板保存的值写入 `$DSH
 - 下载不带任何鉴权，私有存储要提供预签名链接或临时下载链接。
 - 单文件大小和下载耗时有上限（默认 512 MiB、10 分钟），在「日志下载」中调整。
 
-## SKILL 改进（可选）
+## SKILL 改进
+
+分析中 SKILL 没覆盖到的问题，以及用户指出的 SKILL 错误，观象会在用户同意后修改 SKILL 并整理为案例，以合并请求的形式交给你评审。默认开启，可以在设置面板「高级」→「SKILL 改进」关闭。
+
+改进有两个来源：
+
+- **分析时发现不足。** 分析子 Agent 觉得 SKILL 没能支撑这次分析时，在运行目录记下哪里不足、实际怎样定位、依据的日志行和代码位置。父 Agent 照常回复分析结论，然后询问用户是否改进。
+- **用户主动要求。** 用户指出某次分析套用的 SKILL 记录有错，或者在新会话里直接说要优化某个应用的日志分析 SKILL。父 Agent 先读出现有 SKILL，和用户确认哪部分不对、正确做法是什么、有没有样例日志，问清后询问是否改进。
 
-观象可以把分析中发现的 SKILL 欠缺提交为合并请求。默认关闭，在设置面板「高级」→「SKILL 改进」开启。
+之后的流程相同：
 
-流程：子 Agent 把修改后的完整文件和理由写到运行目录 → 观象校验并生成 diff → 父 Agent 在回复中展示改动并请求授权（飞书里是决策卡片，Web 里是审批提示）→ 用户点「允许」后，观象经 dsh-repo 以分析时的提交为起点建新分支 `logalyze/skill-<应用 id>-<改动摘要前缀>`，提交改动，并创建合入跟踪分支的合并请求（GitLab MR 或 GitHub PR）。
+1. 询问在飞书里是决策卡片，在 Web 里是审批提示。
+2. 用户点「允许」后，观象派一个改进子 Agent，按观象自带的改进指南 `/logalyze-improve` 修改 SKILL：把可复用的排查知识补进或改正到 `SKILL.md` 或 `references/`；对应具体问题时写一份案例 `cases/<日期>-<slug>.md`（现象、脱敏的日志特征、根因、定位路径、确认与排除），并在「案例索引」加一行。依据一次分析时必须有案例。
+3. 观象检查改动后，经 `dshRepos` 服务以最新提交为起点建新分支 `logalyze/skill-<应用 id>-<改动摘要前缀>`，提交改动，并创建合入跟踪分支的合并请求（GitLab MR 或 GitHub PR）。回复里列出改动的文件和要点，附合并请求链接。
 
 前提与限制：
 
-- **权限模式必须是「询问」类。** 会话的审批策略为 `never`（DSH「完全访问」模式）时授权请求一律被拒绝，不会推送。
-- **支持 GitLab（包括自建实例）和 GitHub。** 应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 dsh-repo 识别为已配置主机上的仓库，该主机的令牌要有上面列出的写权限。
-- **合并请求以 dsh-repo 令牌主人的身份创建。** 提交作者是观象配置的 `skillUpdateAuthor`，省略时也是令牌主人。
-- **改动范围只限 `.dsh/skills/<skill>/`。** 观象不提交到已有分支和默认分支，合并由仓库的评审流程决定，合并后下一次 `/logalyze` 生效。
+- **权限模式必须是「询问」类。** 会话的审批策略为 `never`（DSH「完全访问」模式）时询问一律被拒绝，不会起草和推送。
+- **支持 GitLab（包括自建实例）和 GitHub。** 应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 `dshRepos` 识别为已配置主机上的仓库，该主机的令牌要有上面列出的写权限。
+- **合并请求以该主机令牌主人的身份创建。** 提交作者是观象配置的 `skillUpdateAuthor`，省略时也是令牌主人。
+- **改动范围只限 `.agents/skills/<skill>/`，依据一次分析时必须包含一份案例。** 观象不提交到已有分支和默认分支，合并由仓库的评审流程决定，合并后下一次 `/logalyze` 生效。
 
 应用仓库维护者应当：
 
 - 保护默认分支，要求合并请求评审后才能合入。
-- 用 CODEOWNERS 等方式为 `.dsh/skills/` 指定评审人。
-- 评审时留意改动内容。日志内容不可信，可能诱导模型写出不当的 SKILL；观象只限制改动范围，不判断内容。
+- 用 CODEOWNERS 等方式为 `.agents/skills/` 指定评审人。
+- 评审时留意改动内容，尤其是案例里的日志片段是否已脱敏。日志内容不可信，可能诱导模型写出不当的 SKILL；观象只限制改动范围，不判断内容。
 
 ## 自检与排错
 
@@ -199,14 +241,15 @@ DSH Web 左侧栏「观象」打开设置面板。面板保存的值写入 `$DSH
 
 | 面板显示 | 处理 |
 |---|---|
-| 仓库缺少应用描述 `.dsh/logalyze.yaml` | 确认文件已推送到跟踪分支，路径和文件名正确 |
-| `.dsh/logalyze.yaml` 不合法：… | 按提示修正字段，`id` 和 `skill` 只能是小写字母、数字和短横线 |
-| 仓库缺少日志分析 SKILL `.dsh/skills/<skill>/SKILL.md` | 目录名要与 `skill` 字段一致 |
+| 仓库缺少应用描述 `.agents/logalyze.yaml` | 确认文件已推送到跟踪分支，路径和文件名正确 |
+| `.agents/logalyze.yaml` 不合法：… | 按提示修正字段，`id` 和 `skill` 只能是小写字母、数字和短横线 |
+| 仓库缺少日志分析 SKILL `.agents/skills/<skill>/SKILL.md` | 目录名要与 `skill` 字段一致 |
 | … 设置了 `user-invocable: false` … | 删除该设置 |
 | … 不是普通文件 | 把符号链接换成真实文件 |
 | 多个仓库声明同一个应用 id | 给其中一个仓库换 `id` |
-| 观象需要 dsh-repo 插件… / dsh-repo 的服务与观象不兼容… | 安装或换用兼容版本的 dsh-repo |
-| 拉取失败（认证、令牌未设置） | 检查「访问令牌」中的主机地址和令牌权限；ssh 地址检查本机 SSH key |
+| 观象需要 dsh-repo 插件… / dsh-repo 的服务与观象不兼容… | 安装或换用提供 `dshRepos` 服务版本 1 的插件 |
+| 拉取失败（认证、令牌未设置） | 检查 dsh-repo 中的主机地址和令牌权限；ssh 地址检查本机 SSH key |
+| 面板可用，但子 Agent 加载的 SKILL 不是 `.agents/skills/<skill>/` 下这份 | 删除仓库里 `.dsh/skills/` 下的同名 SKILL：DSH 同名时优先加载 `.dsh/skills/` |
 
 面板显示可用但子 Agent 没有按 SKILL 工作时，先检查 SKILL frontmatter 的 `name` 是否与 `skill` 字段一致。
 

package/examples/order-service/{.dsh → .agents}/logalyze.yaml

@@ -4,4 +4,4 @@ name: 订单服务
 description: 下单、库存扣减与支付回调
 aliases: [订单, 下单, order]
 logHints: [order-service, OrderController, OrderService]
-skill: log-analysis            # 对应 .dsh/skills/log-analysis/SKILL.md
+skill: log-analysis            # 对应 .agents/skills/log-analysis/SKILL.md

package/examples/order-service/README.md

@@ -3,10 +3,10 @@
 演示观象要求的应用仓库结构：
 
 ```
-.dsh/logalyze.yaml                 应用描述（id、名称、别名、日志特征、分析 SKILL 名）
-.dsh/skills/log-analysis/SKILL.md   日志分析 SKILL，观象派发时用 /log-analysis 加载
-src/                                应用代码，子 Agent 对照它定位根因
-sample-logs/order-service.log       一份示例日志（促销商品没有 SKU 导致 NullPointerException）
+.agents/logalyze.yaml                  应用描述（id、名称、别名、日志特征、分析 SKILL 名）
+.agents/skills/log-analysis/SKILL.md   日志分析 SKILL，观象派发时用 /log-analysis 加载
+src/                                   应用代码，子 Agent 对照它定位根因
+sample-logs/order-service.log          一份示例日志（促销商品没有 SKU 导致 NullPointerException）
 ```
 
 本地试用：把本目录复制出来初始化为 git 仓库，再在「观象」面板中添加它的绝对路径作为 git 地址。

package/lib/client.js

@@ -213,8 +213,8 @@ window.__ModuleLoader__.load({
 		function fromDraft(draft) {
 			const maxApps = positive(draft.maxAppsPerRequest, "单次应用数上限");
 			if (!Number.isInteger(maxApps)) throw new Error("单次应用数上限必须是整数");
-			const maxFiles = positive(draft.skillMaxFiles, "提议文件数上限");
-			if (!Number.isInteger(maxFiles)) throw new Error("提议文件数上限必须是整数");
+			const maxFiles = positive(draft.skillMaxFiles, "改进文件数上限");
+			if (!Number.isInteger(maxFiles)) throw new Error("改进文件数上限必须是整数");
 			return {
 				repos: draft.repos.map((repo) => repo.branch === void 0 || repo.branch.trim() === "" ? { url: repo.url.trim() } : {
 					url: repo.url.trim(),
@@ -231,7 +231,7 @@ window.__ModuleLoader__.load({
 				skillUpdates: {
 					enabled: draft.skillUpdatesEnabled,
 					maxFiles,
-					maxFileBytes: Math.round(positive(draft.skillMaxKb, "提议单文件大小上限") * KB)
+					maxFileBytes: Math.round(positive(draft.skillMaxKb, "改进单文件大小上限") * KB)
 				},
 				analyze: { enabled: draft.analyzeEnabled }
 			};
@@ -696,7 +696,7 @@ window.__ModuleLoader__.load({
 							"。https 地址使用 dsh-repo 中对应主机的令牌，主机或令牌变更后会自动重新拉取，ssh 地址和其他主机使用本机已有的 git 凭据（SSH key 或 credential helper）。不留分支时跟随远端默认分支。每个仓库需包含 ",
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 								className: "lz__mono",
-								children: ".dsh/logalyze.yaml"
+								children: ".agents/logalyze.yaml"
 							}),
 							" 与其中声明的日志分析 SKILL。删除地址不会删除本地镜像。"
 						]
@@ -1149,20 +1149,20 @@ window.__ModuleLoader__.load({
 									className: "lz__rowText",
 									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 										className: "lz__rowLabel",
-										children: ["允许提出 SKILL 修改 ", /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Overridden, {
+										children: ["询问是否改进 SKILL ", /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Overridden, {
 											keys: overridden,
 											name: "skillUpdates"
 										})]
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 										className: "lz__rowSummary",
-										children: "子 Agent 发现应用的日志分析 SKILL 有欠缺时可以写出修改提议；经用户授权后，观象经 dsh-repo 把它提交到新分支并创建合并请求（GitLab 或 GitHub，需要安装 dsh-repo 并配置该仓库主机的令牌）。"
+										children: "子 Agent 觉得应用的日志分析 SKILL 不够用时记下不足，分析结束后询问用户是否改进；用户同意后，改进子 Agent 把问题整理为案例并修改 SKILL，观象经 dsh-repo 提交到新分支并创建合并请求（GitLab 或 GitHub，需要安装 dsh-repo 并配置该仓库主机的令牌）。"
 									})]
 								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 									className: "lz__rowCtl",
 									children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
 										type: "checkbox",
 										className: "lz__check",
-										"aria-label": "允许提出 SKILL 修改",
+										"aria-label": "询问是否改进 SKILL",
 										checked: draft.skillUpdatesEnabled,
 										onChange: (event) => {
 											setDraft({
@@ -1174,7 +1174,7 @@ window.__ModuleLoader__.load({
 								})]
 							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)(NumberRow, {
-								label: "提议文件数上限",
+								label: "改进文件数上限",
 								unit: "个",
 								value: draft.skillMaxFiles,
 								onChange: (value) => {
@@ -1185,7 +1185,7 @@ window.__ModuleLoader__.load({
 								}
 							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)(NumberRow, {
-								label: "提议单文件大小上限",
+								label: "改进单文件大小上限",
 								unit: "KB",
 								value: draft.skillMaxKb,
 								onChange: (value) => {