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

package/README.md

@@ -64,7 +64,8 @@
 - **代码快照不可变。** 子 Agent 在 `dshRepos` 服务按提交创建的只读快照里工作，派发期间持有快照，结束后释放。
 - **运行目录。** 每次派发在父会话目录下创建 `.logalyze/runs/<runId>/<序号>-<应用 id>/`，下载的日志放在这里，子 Agent 也只在这里写文件；应用仓库对子 Agent 只读。
 - **等待式派发。** 工具等待所有子 Agent 结束后一次返回，一条消息对应一张完整回复；超过派发超时或调用被取消时停止仍在运行的子 Agent。子会话中不提供派发工具。
-- **SKILL 改进（可选，默认关闭）。** 子 Agent 发现应用的日志分析 SKILL 有欠缺时，可以在运行目录写出修改提议；经用户授权后，观象经 `dshRepos` 服务把它提交到应用仓库的新分支并创建合并请求（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,9 +105,9 @@ npm 发行包已包含构建产物；本地 `link:` 安装前必须先执行 `pn
     refreshWaitMs: 15000               # 加载 /logalyze 时等待 fetch 的上限；0 = 不等待
     autoInvoke: true                   # 任务匹配已注册应用时模型可自行加载入口 SKILL；false = 只能输入 /logalyze
     skillUpdates:                      # SKILL 改进，见下文
-      enabled: false                   # 默认关闭
-      maxFiles: 16                     # 一次提议最多新增或修改的文件数
-      maxFileBytes: 262144             # 提议中单个文件的大小上限
+      enabled: true                    # 默认开启；false = 子 Agent 不记录 SKILL 不足，也不询问
+      maxFiles: 16                     # 一次改进最多新增或修改的文件数
+      maxFileBytes: 262144             # 改进中单个文件和 SKILL 不足记录的大小上限
     skillUpdateAuthor:                 # 可选：SKILL 改进提交的作者；省略时是该主机令牌的主人
       name: 观象
       email: logalyze@example.com
@@ -134,7 +135,7 @@ DSH Web 左侧栏的「观象」入口打开整页设置面板：
 | 应用仓库 | git 地址列表（分支可选）、每个仓库的拉取状态、提交号、应用描述与不可用原因，单个或全部重新拉取，以及跳转到 dsh-repo 主机与令牌设置的按钮 |
 | 日志下载 | 允许下载的域名、单文件大小上限、下载超时 |
 | 分析接口 | [日志平台分析接口](#日志平台分析接口)的开关、访问令牌（只显示是否已设置）、飞书渠道是否就绪，以及调用地址与字段摘要 |
-| 高级 | 更新间隔、单次应用数上限、派发超时、SKILL 改进开关与提议上限，恢复 cordis.yml 配置 |
+| 高级 | 更新间隔、单次应用数上限、派发超时、SKILL 改进开关与文件上限，恢复 cordis.yml 配置 |
 
 面板保存的值写入 `$DSH_HOME/logalyze/settings.json`（只保存与 cordis.yml 不同的字段），按与配置相同的规则校验；分析接口令牌存入 DSH 凭据库。面板接口 `/logalyze/*` 使用 DSH 自己的登录与来源校验，写操作另做同源校验。
 
@@ -159,20 +160,37 @@ skill: log-analysis             # 对应 .agents/skills/log-analysis/SKILL.md
 
 ## SKILL 改进
 
-开启 `skillUpdates.enabled`（设置面板「高级」→「SKILL 改进」）后，分析中发现的 SKILL 欠缺可以经用户授权后提交为合并请求。提交和创建合并请求经 `dshRepos` 服务完成，应用仓库所在的主机要在提供该服务的插件中配置令牌；没有该服务或版本不符时工具报错。
+`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 的任务消息多出一节说明：把要改的文件从 `.agents/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>-<改动摘要前缀>`，提交 `.agents/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`）要能被 `dshRepos` 识别为已配置主机上的仓库；该主机的令牌在 GitLab 上需要 `api` 权限，在 GitHub 上需要 Contents 和 Pull requests 的读写权限。
 - 有写权限的令牌可以改动它能访问的所有项目。建议用只覆盖应用仓库的项目或组访问令牌，设置过期时间，并保护应用仓库的默认分支。
 - 合并请求以该主机令牌主人的身份创建，提交作者是 `skillUpdateAuthor`，省略时也是令牌主人。飞书群里点「允许」的人可能不是令牌主人；合并请求描述写明了来源会话与分析提交。
-- 日志内容不可信，可能诱导模型写出不当的 SKILL。观象只限制改动范围，内容需要授权的人和合并请求的评审者把关。
+- 日志内容不可信，可能诱导模型写出不当的 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` 拉取即启用该应用。用户拒绝提交时，初稿文件仍在运行目录中，可以手动提交。
 
 ## 日志平台分析接口
 
@@ -254,11 +272,14 @@ pnpm check        # 类型检查（Host 与 Client）+ 单元测试 + 构建 +
 | 路径 | 内容 |
 |---|---|
 | `src/index.ts` | Cordis 插件入口 |
-| `src/service.ts` | 生效设置、注册表、入口 SKILL 与派发工具的注册 |
+| `src/service.ts` | 生效设置、注册表、入口 SKILL 与各工具的注册 |
 | `src/repos/` | `dshRepos` 服务需求与查找、应用描述校验、应用注册表 |
-| `src/skill/entry.ts` | `/logalyze` 入口 SKILL |
-| `src/dispatch/` | 派发工具、日志下载、子 Agent 首条消息 |
-| `src/skill-update/` | SKILL 修改提议的校验、diff、授权与提交 |
+| `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

@@ -14,10 +14,10 @@
 
 ## 接入清单
 
-1. 在仓库里新增 `.agents/logalyze.yaml`，见[应用描述](#应用描述)。
+1. 在仓库里新增 `.agents/logalyze.yaml`，见[应用描述](#应用描述)。也可以在仓库里运行装有观象的 dsh，输入 `/logalyze-kit`，让模型按观象自带的接入套件起草这一步和下一步的文件。
 2. 在仓库里新增 `.agents/skills/<skill>/SKILL.md`，见[日志分析 SKILL](#日志分析-skill)。
 3. 把这两个文件推送到观象跟踪的分支（默认是远端默认分支）。观象读取的是远端最新提交，不读任何本地检出。
-4. 在设置面板「应用仓库」中添加 git 地址；https 私有仓库另在 dsh-repo 中为它所在的主机配置令牌，见[在设置面板接入](#在设置面板接入)。
+4. 在设置面板「应用仓库」中添加 git 地址，或在对话中让观象添加（见[在对话中接入](#在对话中接入)）；https 私有仓库另在 dsh-repo 中为它所在的主机配置令牌，见[在设置面板接入](#在设置面板接入)。
 5. 日志以对象存储链接提供时，在「日志下载」中加入该域名。
 6. 面板中该仓库显示为可用后，发一条 `/logalyze <问题>`，附上日志试跑。
 
@@ -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#安装与配置)）。
@@ -164,7 +198,7 @@ DSH Web 左侧栏「观象」打开设置面板。面板保存的值写入 `$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 读写权限。
+- 令牌权限：只拉取时，GitLab 需要 `read_repository`，GitHub 需要 Contents 读权限。开启 [SKILL 改进](#skill-改进) 时，GitLab 需要 `api`，GitHub 需要 Contents 和 Pull requests 读写权限。
 - **建议使用项目访问令牌**（或组访问令牌）：只覆盖要接入的应用仓库，设置过期时间。个人令牌能访问令牌主人有权限的所有项目，加了写权限后风险更大。
 
 ### 日志下载
@@ -173,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 里是审批提示）→ 用户点「允许」后，观象经 `dshRepos` 服务以分析时的提交为起点建新分支 `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「完全访问」模式）时授权请求一律被拒绝，不会推送。
+- **权限模式必须是「询问」类。** 会话的审批策略为 `never`（DSH「完全访问」模式）时询问一律被拒绝，不会起草和推送。
 - **支持 GitLab（包括自建实例）和 GitHub。** 应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 `dshRepos` 识别为已配置主机上的仓库，该主机的令牌要有上面列出的写权限。
 - **合并请求以该主机令牌主人的身份创建。** 提交作者是观象配置的 `skillUpdateAuthor`，省略时也是令牌主人。
-- **改动范围只限 `.agents/skills/<skill>/`。** 观象不提交到已有分支和默认分支，合并由仓库的评审流程决定，合并后下一次 `/logalyze` 生效。
+- **改动范围只限 `.agents/skills/<skill>/`，依据一次分析时必须包含一份案例。** 观象不提交到已有分支和默认分支，合并由仓库的评审流程决定，合并后下一次 `/logalyze` 生效。
 
 应用仓库维护者应当：
 
 - 保护默认分支，要求合并请求评审后才能合入。
 - 用 CODEOWNERS 等方式为 `.agents/skills/` 指定评审人。
-- 评审时留意改动内容。日志内容不可信，可能诱导模型写出不当的 SKILL；观象只限制改动范围，不判断内容。
+- 评审时留意改动内容，尤其是案例里的日志片段是否已脱敏。日志内容不可信，可能诱导模型写出不当的 SKILL；观象只限制改动范围，不判断内容。
 
 ## 自检与排错
 

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 }
 			};
@@ -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) => {