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

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,14 @@
 父 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-改进)。
+- **SKILL 改进（可选，默认关闭）。** 子 Agent 发现应用的日志分析 SKILL 有欠缺时，可以在运行目录写出修改提议；经用户授权后，观象经 `dshRepos` 服务把它提交到应用仓库的新分支并创建合并请求（GitLab MR 或 GitHub PR），见 [SKILL 改进](#skill-改进)。
 
 ## 安装与配置
 
@@ -107,7 +107,7 @@ npm 发行包已包含构建产物；本地 `link:` 安装前必须先执行 `pn
       enabled: false                   # 默认关闭
       maxFiles: 16                     # 一次提议最多新增或修改的文件数
       maxFileBytes: 262144             # 提议中单个文件的大小上限
-    skillUpdateAuthor:                 # 可选：SKILL 改进提交的作者；省略时是 dsh-repo 中该主机令牌的主人
+    skillUpdateAuthor:                 # 可选：SKILL 改进提交的作者；省略时是该主机令牌的主人
       name: 观象
       email: logalyze@example.com
     analyze:                           # 日志平台分析接口，见下文
@@ -117,16 +117,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；没有 dsh-repo 或其服务版本不兼容时仓库拉取失败，原因显示在设置面板。
+观象自己不运行 git，也不依赖其他插件的包。拉取镜像、读取提交、创建只读快照和提交 SKILL 修改都调用运行时的 `dshRepos` 服务（服务版本 1，例如由 [dsh-repo](https://github.com/modestoma/dsh-repo) 提供），它用到的方法见 `src/repos/contract.ts`。没有该服务或服务版本不符时仓库拉取失败，原因显示在设置面板。
 
-- **镜像与快照在 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 凭据库，面板只显示是否已设置。ssh 地址、`user@host:path`、其他主机和本地路径使用本机已有的 git 凭据（SSH key 或 credential helper），不会弹出交互式输入。
+主机、访问令牌和镜像目录都在提供 `dshRepos` 的插件中配置；观象面板「应用仓库」分页的「管理主机与令牌」跳到 dsh-repo 的设置页。该服务报告主机或令牌变更后，观象自动重新拉取全部仓库。
 
-凭据库文件只防其他系统用户。与 DSH 中的模型 API Key 一样，Agent 的命令以同一系统用户运行，文件权限不能把令牌与 Agent 隔离（见 `@deepseek-ai/dsh-credentials-local` 文档）；建议使用权限最小、设置过期时间的令牌。
-
-子 Agent 的命令在 dsh 的文件沙箱中运行：仓库只读，只有父会话的项目目录可写，运行目录就在其中。Linux 的 bubblewrap 沙箱会把 `/tmp` 换成空的临时目录，所以 dsh-repo 的 `mirror.dir` 不要放在 `/tmp` 下，否则子 Agent 的命令看不到仓库。
+子 Agent 的命令在 dsh 的文件沙箱中运行：仓库只读，只有父会话的项目目录可写，运行目录就在其中。Linux 的 bubblewrap 沙箱会把 `/tmp` 换成空的临时目录，所以镜像目录不要放在 `/tmp` 下，否则子 Agent 的命令看不到仓库。
 
 ### 设置面板
 
@@ -134,19 +131,18 @@ DSH Web 左侧栏的「观象」入口打开整页设置面板：
 
 | 分页 | 内容 |
 |---|---|
-| 应用仓库 | git 地址列表（分支可选）、每个仓库的拉取状态、提交号、应用描述与不可用原因，单个或全部重新拉取 |
-| 访问令牌 | dsh-repo 的主机列表：选 GitLab 或 GitHub，填地址、别名和令牌即可添加，立即生效。每行显示令牌是否已设置及来源，可替换或清除；面板添加的主机可以删除，dsh-repo cordis.yml 中的主机只能改令牌 |
+| 应用仓库 | git 地址列表（分支可选）、每个仓库的拉取状态、提交号、应用描述与不可用原因，单个或全部重新拉取，以及跳转到 dsh-repo 主机与令牌设置的按钮 |
 | 日志下载 | 允许下载的域名、单文件大小上限、下载超时 |
 | 分析接口 | [日志平台分析接口](#日志平台分析接口)的开关、访问令牌（只显示是否已设置）、飞书渠道是否就绪，以及调用地址与字段摘要 |
 | 高级 | 更新间隔、单次应用数上限、派发超时、SKILL 改进开关与提议上限，恢复 cordis.yml 配置 |
 
-面板保存的值写入 `$DSH_HOME/logalyze/settings.json`（只保存与 cordis.yml 不同的字段），按与配置相同的规则校验；主机保存在 dsh-repo，令牌值存入 DSH 凭据库。面板接口 `/logalyze/*` 使用 DSH 自己的登录与来源校验，写操作另做同源校验。
+面板保存的值写入 `$DSH_HOME/logalyze/settings.json`（只保存与 cordis.yml 不同的字段），按与配置相同的规则校验；分析接口令牌存入 DSH 凭据库。面板接口 `/logalyze/*` 使用 DSH 自己的登录与来源校验，写操作另做同源校验。
 
 ## 应用仓库约定
 
-每个应用仓库需要两样东西（完整示例见 [examples/order-service](examples/order-service)）：
+每个应用仓库需要两样东西（完整示例见 [examples/order-service](examples/order-service)，接入步骤与 SKILL 写作要点见[应用仓库接入指南](docs/app-repo-guide.md)）：
 
-`.dsh/logalyze.yaml` 应用描述：
+`.agents/logalyze.yaml` 应用描述：
 
 ```yaml
 id: order-service               # 小写短横线格式，派发与分析请求按它对应应用
@@ -154,28 +150,28 @@ 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` 或面板「访问令牌」）；没有该服务或版本不符时工具报错。
+开启 `skillUpdates.enabled`（设置面板「高级」→「SKILL 改进」）后，分析中发现的 SKILL 欠缺可以经用户授权后提交为合并请求。提交和创建合并请求经 `dshRepos` 服务完成，应用仓库所在的主机要在提供该服务的插件中配置令牌；没有该服务或版本不符时工具报错。
 
-1. **子 Agent 写提议。** 子 Agent 的任务消息多出一节说明：把要改的文件从 `.dsh/skills/<skill>/` 复制到运行目录的 `skill-proposal/files/`（保持相对路径）后修改，理由写进 `skill-proposal/reason.md`。仓库对子 Agent 仍然只读。
+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>-<改动摘要前缀>`，提交 `.dsh/skills/<skill>/` 下有改动的文件，再创建合入跟踪分支的合并请求，返回它的链接。同一改动的分支已存在时不再请求授权，也不提交；等待授权期间分支被别人建出时同样不提交。从不提交到已有分支或默认分支，合并由仓库的评审流程决定；合并后下次 `/logalyze` 拉取即生效。提交成功但合并请求创建失败时，工具返回分支和失败原因，可以在代码托管平台上手动创建。
+5. **提交新分支并创建合并请求。** 观象进程（不是 Agent）经 `dshRepos` 以分析时的提交为起点建新分支 `logalyze/skill-<应用 id>-<改动摘要前缀>`，提交 `.agents/skills/<skill>/` 下有改动的文件，再创建合入跟踪分支的合并请求，返回它的链接。同一改动的分支已存在时不再请求授权，也不提交；等待授权期间分支被别人建出时同样不提交。从不提交到已有分支或默认分支，合并由仓库的评审流程决定；合并后下次 `/logalyze` 拉取即生效。提交成功但合并请求创建失败时，工具返回分支和失败原因，可以在代码托管平台上手动创建。
 
 注意：
 
-- 支持 GitLab（包括自建实例）和 GitHub。应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 dsh-repo 识别为已配置主机上的仓库；dsh-repo 的令牌在 GitLab 上需要 `api` 权限，在 GitHub 上需要 Contents 和 Pull requests 的读写权限。
-- 有写权限的令牌可以改动它能访问的所有项目。建议用只覆盖应用仓库的项目或组访问令牌，设置过期时间，用 dsh-repo 的 `repos` 限定范围，并保护应用仓库的默认分支。
-- 合并请求以 dsh-repo 令牌主人的身份创建，提交作者是 `skillUpdateAuthor`，省略时也是令牌主人。飞书群里点「允许」的人可能不是令牌主人；合并请求描述写明了来源会话与分析提交。
+- 支持 GitLab（包括自建实例）和 GitHub。应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 `dshRepos` 识别为已配置主机上的仓库；该主机的令牌在 GitLab 上需要 `api` 权限，在 GitHub 上需要 Contents 和 Pull requests 的读写权限。
+- 有写权限的令牌可以改动它能访问的所有项目。建议用只覆盖应用仓库的项目或组访问令牌，设置过期时间，并保护应用仓库的默认分支。
+- 合并请求以该主机令牌主人的身份创建，提交作者是 `skillUpdateAuthor`，省略时也是令牌主人。飞书群里点「允许」的人可能不是令牌主人；合并请求描述写明了来源会话与分析提交。
 - 日志内容不可信，可能诱导模型写出不当的 SKILL。观象只限制改动范围，内容需要授权的人和合并请求的评审者把关。
 
 ## 日志平台分析接口
@@ -246,7 +242,7 @@ pnpm check        # 类型检查（Host 与 Client）+ 单元测试 + 构建 +
 
 ## 发布
 
-版本号由 semantic-release 按 Conventional Commits 计算。推送到 `dev` 后，检查通过就自动发布 beta；正式版**只在手动触发时发布**，推送到 `main` 只跑检查。只有 `feat`、`fix` 或破坏性变更会产生新版本，其余类型的提交不发布。PR 标题需符合 `<type>(<scope>): <summary>`，type 取 `feat | fix | docs | test | refactor | chore | ci`。
+版本号由 semantic-release 按 Conventional Commits 计算，并始终保持 0.x：破坏性变更只升次版本号（如 0.2 → 0.3），不会升到 1.0.0。推送到 `dev` 后，检查通过就自动发布 beta；正式版**只在手动触发时发布**，推送到 `main` 只跑检查。只有 `feat`、`fix` 或破坏性变更会产生新版本，其余类型的提交不发布。PR 标题需符合 `<type>(<scope>): <summary>`，type 取 `feat | fix | docs | test | refactor | chore | ci`。
 
 | 分支 | 触发 | 版本 | npm dist-tag |
 | --- | --- | --- | --- |
@@ -259,7 +255,7 @@ pnpm check        # 类型检查（Host 与 Client）+ 单元测试 + 构建 +
 |---|---|
 | `src/index.ts` | Cordis 插件入口 |
 | `src/service.ts` | 生效设置、注册表、入口 SKILL 与派发工具的注册 |
-| `src/repos/` | dsh-repo 服务查找、应用描述校验、应用注册表 |
+| `src/repos/` | `dshRepos` 服务需求与查找、应用描述校验、应用注册表 |
 | `src/skill/entry.ts` | `/logalyze` 入口 SKILL |
 | `src/dispatch/` | 派发工具、日志下载、子 Agent 首条消息 |
 | `src/skill-update/` | SKILL 修改提议的校验、diff、授权与提交 |

package/docs/app-repo-guide.md

@@ -0,0 +1,213 @@
+# 应用仓库接入指南
+
+本文写给应用代码仓库的维护者：一个应用要被观象分析，仓库里需要放什么、观象那边需要配什么。
+
+## 分工
+
+观象只负责识别与派发；怎么分析某个应用的日志，由应用仓库自己的 SKILL 决定。
+
+| 谁 | 做什么 |
+|---|---|
+| 应用仓库 | 提供应用描述 `.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. 在仓库里新增 `.agents/logalyze.yaml`，见[应用描述](#应用描述)。
+2. 在仓库里新增 `.agents/skills/<skill>/SKILL.md`，见[日志分析 SKILL](#日志分析-skill)。
+3. 把这两个文件推送到观象跟踪的分支（默认是远端默认分支）。观象读取的是远端最新提交，不读任何本地检出。
+4. 在设置面板「应用仓库」中添加 git 地址；https 私有仓库另在 dsh-repo 中为它所在的主机配置令牌，见[在设置面板接入](#在设置面板接入)。
+5. 日志以对象存储链接提供时，在「日志下载」中加入该域名。
+6. 面板中该仓库显示为可用后，发一条 `/logalyze <问题>`，附上日志试跑。
+
+## 最小示例
+
+```
+order-service/
+├── .agents/
+│   ├── logalyze.yaml
+│   └── skills/
+│       └── log-analysis/
+│           └── SKILL.md
+└── src/ …
+```
+
+`.agents/logalyze.yaml`：
+
+```yaml
+id: order-service
+name: 订单服务
+description: 下单、库存扣减与支付回调
+aliases: [订单, 下单]
+logHints: [order-service, OrderController]
+skill: log-analysis
+```
+
+`.agents/skills/log-analysis/SKILL.md`：
+
+```markdown
+---
+name: log-analysis
+description: 订单服务的日志分析流程：解压日志包、定位异常、对照本仓库代码给出根因。
+---
+
+# 订单服务日志分析
+
+仓库只读；解压和中间文件只放在任务消息给出的运行目录。
+
+## 1. 准备日志
+- `.tar.gz` / `.tgz`：`tar -xzf <日志包> -C <运行目录>`
+- `.zip`：`unzip -o <日志包> -d <运行目录>`
+- 纯文本日志直接读取，不要复制。
+
+## 2. 定位异常
+- 日志格式：`时间 级别 [线程] [traceId] 类名 - 消息`。
+- 先按时间范围和订单号、traceId 用 `grep` 过滤，再看第一条 `ERROR` / `Caused by`。
+
+## 3. 对照代码
+- `com.example.order.*` 位于 `src/main/java/com/example/order/`。
+- `InventoryClient` 返回 503 或超时属于库存服务问题，不是本服务缺陷。
+```
+
+完整的可运行示例（含示例日志和代码）见 [examples/order-service](../examples/order-service)。
+
+## 应用描述
+
+`.agents/logalyze.yaml` 放在仓库根目录下，必须是普通文件（不能是符号链接）。
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 小写短横线格式，如 `order-service`。派发和分析请求按它找到应用，在所有接入的仓库中必须唯一 |
+| `name` | 是 | 显示名，也是子 Agent 的标签，如「订单服务分析」 |
+| `description` | 是 | 一句话说明应用负责什么，出现在入口 SKILL 的应用目录里 |
+| `aliases` | 否 | 用户对这个应用的其他叫法，如中文名简称、英文名 |
+| `logHints` | 否 | 能从日志里认出本应用的字符串，如服务名、主类名、日志 tag |
+| `skill` | 是 | 日志分析 SKILL 名，小写短横线格式；对应 `.agents/skills/<skill>/SKILL.md` |
+
+规则：
+
+- 观象每次加载 `/logalyze` 时先经 `dshRepos` 服务 fetch，再从跟踪分支的最新提交读取应用描述。改了描述或 SKILL，推送后下一次 `/logalyze` 就生效，不用重启。
+- 一个仓库对应一个应用。多个仓库声明同一个 `id` 时，这几个仓库全部不可用。
+- 描述不合法、SKILL 缺失或设置了 `user-invocable: false` 时，应用不可用，原因显示在设置面板。
+
+## 日志分析 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>` 加载不受影响。
+- SKILL 目录里可以放 `scripts/`、`references/` 等辅助文件，子 Agent 可以读取和执行，但它们的输出只能写到运行目录。
+
+### 子 Agent 收到什么
+
+观象为每个应用启动一个子 Agent，工作目录是应用仓库在分析时那个提交的只读快照。它的首条消息大致如下：
+
+```
+/log-analysis
+
+你是观象派发的日志分析子任务，负责应用「订单服务」（id: `order-service`）。当前工作目录是该应用的代码仓库，检出提交 `3f2a9c1e0b7d`。
+
+## 问题
+（父 Agent 整理的现象、时间、关键标识和用户原话要点）
+
+## 日志
+- `/…/.logalyze/runs/<runId>/1-order-service/1-app.tar.gz`（下载自 https://oss.example.com/…）；只看本应用相关部分：tag=order
+
+## 工作约束
+- 应用仓库只读 …
+- 解压结果和中间文件只放在运行目录 `/…/.logalyze/runs/<runId>/1-order-service`。
+
+## 返回格式
+结论、关键证据、时间线、假设与待验证、建议，五部分。
+```
+
+- 日志一律是绝对路径。附件和本机文件直接给原路径；对象存储链接由观象下载到运行目录。日志包不会被预先解压。
+- 一个文件混有多个应用的输出时，会附带 `filter` 说明如何区分。
+- 返回格式由观象固定。SKILL 的「输出」部分只补充本应用特有的要求（比如证据中写哪些标识），不要另定一套结构。
+
+### 写作要点
+
+- **先写解压。** 按本应用实际的日志包格式写清命令，解压目标一律是运行目录。仓库只读，解压到仓库里会失败。
+- **只读，只写运行目录。** 不改仓库文件，不执行 git 写操作，不 `cd` 到别处写文件。
+- **不要依赖需要审批的操作。** 子 Agent 不会弹出审批或提问，通过飞书使用时 dsh_channels 也不转发子 Agent 的审批。联网下载、安装依赖、写运行目录以外的位置、启动服务或容器这类操作会直接失败。需要的工具（`tar`、`unzip`、`rg`、`jq` 等）要在运行 dsh 的机器上预先装好。
+- **先过滤再阅读。** 日志可能很大，先按时间、traceId、订单号等用 `grep`/`rg` 缩小范围，不要通读或整体复制。
+- **写清日志格式和代码地图。** 每行字段的含义、时间格式与时区、关键 logger 名对应的代码目录、调用链上的上下游服务。
+- **写已知故障和排除规则。** 比如「库存服务 503 属于下游问题」。这部分是 SKILL 最有价值的内容，也是 [SKILL 改进](#skill-改进可选) 最常补充的内容。
+- **说明版本对不上时怎么办。** 子 Agent 看的是跟踪分支的最新代码，日志可能来自更早的版本。日志里打印了版本号或提交号时，告诉子 Agent 在哪里找，并在结论中说明版本差异。
+
+## 让观象认出你的应用
+
+用户输入 `/logalyze` 时一定走观象。没有输入时，只要有可用应用且 `autoInvoke` 开启（默认开启），模型也会在任务匹配时自行加载观象，比如用户说「帮我看下订单服务的报错日志」，或贴出带 `OrderController` 的堆栈。应用描述决定匹配效果：
+
+- 模型看到的观象简介由各应用的 `name（id、aliases、logHints）` 拼接而成，**所有应用共用 500 字的上限**，放不下的应用只计数不列出。`aliases` 和 `logHints` 各写两三个最有区分度的词。
+- `aliases` 写用户会说的叫法：中文简称、英文名、业务名。
+- `logHints` 写日志开头几十行就会出现的字符串：服务名、进程名、日志 tag、主类名。入口 SKILL 只允许模型看日志开头几十行来判断归属。不要用 `ERROR`、`Exception` 这种所有应用都有的词。
+- `description` 写这个应用负责的业务，出现在入口 SKILL 的应用目录表格里，帮助模型区分名字相近的应用。
+
+日志明显不属于任何已注册应用时，模型按普通方式处理，不会派发。
+
+## 在设置面板接入
+
+DSH Web 左侧栏「观象」打开设置面板。面板保存的值写入 `$DSH_HOME/logalyze/settings.json`，也可以在 profile 的 cordis.yml 中按 `id: logalyze` 配置默认值（字段见 [README](../README.md#安装与配置)）。
+
+| 分页 | 应用仓库需要的设置 |
+|---|---|
+| 应用仓库 | 填 git 地址，分支可选（默认跟随远端默认分支）。支持 https/http/ssh/git/file URL、`user@host:path` 和绝对路径。拉取后显示提交号、应用描述或不可用原因 |
+| 日志下载 | 日志以链接提供时，把对象存储域名加入白名单（同时允许其子域名） |
+| 高级 | 拉取间隔、单次应用数上限、派发超时、SKILL 改进开关 |
+
+### git 地址与令牌
+
+- 仓库由 `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 读写权限。
+- **建议使用项目访问令牌**（或组访问令牌）：只覆盖要接入的应用仓库，设置过期时间。个人令牌能访问令牌主人有权限的所有项目，加了写权限后风险更大。
+
+### 日志下载
+
+- 只下载 http/https 链接，域名必须在白名单中，链接中不能带用户名和密码。
+- 下载不带任何鉴权，私有存储要提供预签名链接或临时下载链接。
+- 单文件大小和下载耗时有上限（默认 512 MiB、10 分钟），在「日志下载」中调整。
+
+## SKILL 改进（可选）
+
+观象可以把分析中发现的 SKILL 欠缺提交为合并请求。默认关闭，在设置面板「高级」→「SKILL 改进」开启。
+
+流程：子 Agent 把修改后的完整文件和理由写到运行目录 → 观象校验并生成 diff → 父 Agent 在回复中展示改动并请求授权（飞书里是决策卡片，Web 里是审批提示）→ 用户点「允许」后，观象经 `dshRepos` 服务以分析时的提交为起点建新分支 `logalyze/skill-<应用 id>-<改动摘要前缀>`，提交改动，并创建合入跟踪分支的合并请求（GitLab MR 或 GitHub PR）。
+
+前提与限制：
+
+- **权限模式必须是「询问」类。** 会话的审批策略为 `never`（DSH「完全访问」模式）时授权请求一律被拒绝，不会推送。
+- **支持 GitLab（包括自建实例）和 GitHub。** 应用仓库的 git 地址（https、ssh 或 `user@host:path`）要能被 `dshRepos` 识别为已配置主机上的仓库，该主机的令牌要有上面列出的写权限。
+- **合并请求以该主机令牌主人的身份创建。** 提交作者是观象配置的 `skillUpdateAuthor`，省略时也是令牌主人。
+- **改动范围只限 `.agents/skills/<skill>/`。** 观象不提交到已有分支和默认分支，合并由仓库的评审流程决定，合并后下一次 `/logalyze` 生效。
+
+应用仓库维护者应当：
+
+- 保护默认分支，要求合并请求评审后才能合入。
+- 用 CODEOWNERS 等方式为 `.agents/skills/` 指定评审人。
+- 评审时留意改动内容。日志内容不可信，可能诱导模型写出不当的 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 的服务与观象不兼容… | 安装或换用提供 `dshRepos` 服务版本 1 的插件 |
+| 拉取失败（认证、令牌未设置） | 检查 dsh-repo 中的主机地址和令牌权限；ssh 地址检查本机 SSH key |
+| 面板可用，但子 Agent 加载的 SKILL 不是 `.agents/skills/<skill>/` 下这份 | 删除仓库里 `.dsh/skills/` 下的同名 SKILL：DSH 同名时优先加载 `.dsh/skills/` |
+
+面板显示可用但子 Agent 没有按 SKILL 工作时，先检查 SKILL frontmatter 的 `name` 是否与 `skill` 字段一致。
+
+本地试用可以先用 [examples/order-service](../examples/order-service)：把它复制出来初始化为 git 仓库，在面板添加它的绝对路径，然后按示例 README 中的消息试跑。

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 地址。