@modesto_ma/dsh-guanxiang 0.1.0-beta.2 → 0.1.0

package/src/skill/entry.ts

@@ -9,6 +9,7 @@
 import type { SkillDefinition, SkillProvider, SkillProviderControl } from '../host.ts'
 import type { AppManifest } from '../settings/contract.ts'
 import { DISPATCH_TOOL_NAME } from '../dispatch/tool.ts'
+import { PROPOSE_TOOL_NAME } from '../skill-update/tool.ts'
 
 /** Entry skill name, addressed as `/guanxiang`. */
 export const ENTRY_SKILL_NAME = 'guanxiang'
@@ -61,13 +62,20 @@ export function renderCatalog(apps: readonly AppManifest[]): string {
   return ['| 应用 id | 名称 | 描述 | 别名 | 日志特征 |', '| --- | --- | --- | --- | --- |', ...rows].join('\n')
 }
 
+function proposalStep(): string {
+  return `
+5. **SKILL 修改提议。** 派发结果中某个应用带有「SKILL 修改提议」时，在汇总回复末尾另起一节「SKILL 修改提议」：说明改动的文件和理由，附上 diff 文件中的关键改动；diff 较长时给出 diff 文件路径，在飞书话题中可以用 \`feishu_send_file\` 发送该文件。然后调用 \`${PROPOSE_TOOL_NAME}\`（\`workDir\` 取结果中给出的运行目录，\`summary\` 一句话说明改了什么）。工具会先请求用户授权，批准后推送新分支并创建合并请求。不要自己用 git 推送或修改仓库。工具返回后，把合并请求链接或「用户拒绝 / 无法授权」如实告诉用户。提议不可提交时，只说明原因。
+`
+}
+
 /**
  * The entry skill body.
  * @param apps - usable applications at load time.
  * @param maxAppsPerRequest - dispatch task ceiling.
+ * @param skillUpdates - whether SKILL improvement proposals are enabled.
  * @returns Markdown instructions.
  */
-export function renderEntrySkill(apps: readonly AppManifest[], maxAppsPerRequest: number): string {
+export function renderEntrySkill(apps: readonly AppManifest[], maxAppsPerRequest: number, skillUpdates: boolean): string {
   return `# 观象：日志分析入口
 
 观其象，知其因。没有 \`${DISPATCH_TOOL_NAME}\` 工具可用时（例如你是子 Agent），忽略本 SKILL，按普通方式完成任务。
@@ -109,7 +117,7 @@ ${renderCatalog(apps)}
 \`\`\`
 
    每个派发的应用都有一节。子 Agent 失败、超时或结论不充分时，在该节如实说明，不要编造结论。日志版本与仓库代码可能不一致，子 Agent 提示了版本差异时保留这条提示。
-`
+${skillUpdates ? proposalStep() : ''}`
 }
 
 /** Inputs the provider reads at each listing and load. */
@@ -126,6 +134,8 @@ export interface EntrySkillSource {
   apps(): readonly AppManifest[]
   /** Current dispatch task ceiling. */
   maxAppsPerRequest(): number
+  /** Whether SKILL improvement proposals are enabled. */
+  skillUpdates(): boolean
   /** Whether top-level agents may load the skill without `/guanxiang`. */
   readonly autoInvoke: boolean
   /**
@@ -176,7 +186,7 @@ export function createEntrySkillProvider(source: EntrySkillSource): {
         get: async (requested, options): Promise<SkillDefinition | undefined> => {
           if (requested.name !== ENTRY_SKILL_NAME) return undefined
           await source.prepare(options.signal)
-          return { ...summary(), content: renderEntrySkill(source.apps(), source.maxAppsPerRequest()) }
+          return { ...summary(), content: renderEntrySkill(source.apps(), source.maxAppsPerRequest(), source.skillUpdates()) }
         },
       }
     },

package/src/skill-update/git.ts

@@ -0,0 +1,157 @@
+/**
+ * 在拉取仓库中用 git 底层命令生成 SKILL 修改的提交并推送：用临时索引文件
+ * 在分析时的提交上替换文件、写出树对象，不改动任何检出、快照或本地分支；
+ * 推送时用 GitLab push options 顺带创建合并请求。
+ *
+ * @module dsh-guanxiang/skill-update/git
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { GitRunner } from '../repos/git.ts'
+import type { ProposedFile } from './proposal.ts'
+
+/** Line counts of one changed file. */
+export interface FileStat {
+  /** Path relative to the repository root. */
+  readonly path: string
+  /** Added lines; undefined for a binary change. */
+  readonly added?: number
+  /** Removed lines; undefined for a binary change. */
+  readonly removed?: number
+}
+
+/** A proposal turned into a tree object on top of its base commit. */
+export interface PreparedChange {
+  readonly base: string
+  readonly tree: string
+  readonly files: readonly FileStat[]
+  /** Unified diff from the base commit to {@link tree}, limited to the skill directory. */
+  readonly diff: string
+}
+
+/** git runner and the timeout of one command. */
+export interface GitCommands {
+  readonly git: GitRunner
+  readonly timeoutMs: number
+}
+
+/** Author and committer of a commit. */
+export interface CommitAuthor {
+  readonly name: string
+  readonly email: string
+}
+
+/** Merge request fields sent as GitLab push options. */
+export interface MergeRequestOptions {
+  readonly target: string
+  readonly title: string
+  readonly description: string
+}
+
+const DIFF_FLAGS = ['--no-color', '--no-ext-diff', '--no-renames']
+
+/**
+ * Write the proposed files over the skill directory of `base` into a new tree.
+ * @param commands - git runner and timeout.
+ * @param dir - repository directory whose object database receives the objects.
+ * @param base - commit the analysis ran on.
+ * @param skillDir - skill directory relative to the repository root, `/`-separated.
+ * @param files - proposed files relative to `skillDir`.
+ * @returns the tree, per-file line counts, and the diff; `files` is empty when nothing changes.
+ * @throws when a proposed path replaces a symbolic link or a directory, or a git command fails.
+ */
+export async function prepareChange(commands: GitCommands, dir: string, base: string, skillDir: string, files: readonly ProposedFile[]): Promise<PreparedChange> {
+  const { git, timeoutMs } = commands
+  const scratch = await mkdtemp(join(tmpdir(), 'guanxiang-index-'))
+  try {
+    const env = { GIT_INDEX_FILE: join(scratch, 'index') }
+    await git(['read-tree', base], { cwd: dir, timeoutMs, env })
+    const listing = await git(['ls-tree', '-r', '-t', '-z', base, '--', `${skillDir}/`], { cwd: dir, timeoutMs })
+    const modes = new Map<string, string>()
+    for (const record of listing.split('\0')) {
+      const tab = record.indexOf('\t')
+      if (tab < 0) continue
+      modes.set(record.slice(tab + 1), record.slice(0, record.indexOf(' ')))
+    }
+    for (const file of files) {
+      const path = `${skillDir}/${file.path}`
+      const existing = modes.get(path)
+      if (existing === '120000') throw new Error(`${path} 在仓库中是符号链接，不能用提议覆盖`)
+      if (existing === '040000') throw new Error(`${path} 在仓库中是目录，不能用文件覆盖`)
+      const blob = (await git(['hash-object', '-w', '--stdin'], { cwd: dir, timeoutMs, input: file.content })).trim()
+      await git(['update-index', '--add', '--cacheinfo', `${existing === '100755' ? '100755' : '100644'},${blob},${path}`], { cwd: dir, timeoutMs, env })
+    }
+    const tree = (await git(['write-tree'], { cwd: dir, timeoutMs, env })).trim()
+    const numstat = await git(['diff', ...DIFF_FLAGS, '--numstat', base, tree, '--', `${skillDir}/`], { cwd: dir, timeoutMs })
+    const stats = numstat.split('\n').filter(line => line !== '').map((line): FileStat => {
+      const [added = '-', removed = '-', ...path] = line.split('\t')
+      return { path: path.join('\t'), ...added === '-' ? {} : { added: Number(added) }, ...removed === '-' ? {} : { removed: Number(removed) } }
+    })
+    const diff = stats.length === 0 ? '' : await git(['diff', ...DIFF_FLAGS, base, tree, '--', `${skillDir}/`], { cwd: dir, timeoutMs })
+    return { base, tree, files: stats, diff }
+  } finally {
+    await rm(scratch, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Whether the remote already has a branch.
+ * @param commands - git runner and timeout.
+ * @param dir - clone directory.
+ * @param branch - branch name.
+ * @param env - network environment of the clone's address.
+ * @returns whether `refs/heads/<branch>` exists on `origin`.
+ */
+export async function remoteBranchExists(commands: GitCommands, dir: string, branch: string, env: Readonly<Record<string, string>>): Promise<boolean> {
+  const output = await commands.git(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], { cwd: dir, timeoutMs: commands.timeoutMs, env })
+  return output.trim() !== ''
+}
+
+/**
+ * Commit a prepared tree on its base commit without touching any ref.
+ * @param commands - git runner and timeout.
+ * @param dir - clone directory.
+ * @param change - prepared tree and its base.
+ * @param message - full commit message.
+ * @param author - explicit identity; omitted uses the host's git configuration.
+ * @returns the new commit id.
+ */
+export async function commitChange(commands: GitCommands, dir: string, change: PreparedChange, message: string, author: CommitAuthor | undefined): Promise<string> {
+  const env = author === undefined
+    ? undefined
+    : { GIT_AUTHOR_NAME: author.name, GIT_AUTHOR_EMAIL: author.email, GIT_COMMITTER_NAME: author.name, GIT_COMMITTER_EMAIL: author.email }
+  const output = await commands.git(['commit-tree', change.tree, '-p', change.base, '-F', '-'], { cwd: dir, timeoutMs: commands.timeoutMs, input: message, ...env === undefined ? {} : { env } })
+  return output.trim()
+}
+
+/** Push options cannot carry line breaks; collapse every whitespace run. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Push a commit to a new remote branch and ask GitLab to open a merge request
+ * for it (`merge_request.*` push options). The push carries an empty lease on
+ * the branch, so it fails instead of updating a branch that appeared after
+ * {@link remoteBranchExists} was checked. A server that does not support push
+ * options rejects the push.
+ * @param commands - git runner and timeout.
+ * @param dir - clone directory.
+ * @param commit - commit to push.
+ * @param branch - new branch name.
+ * @param request - merge request target and text.
+ * @param env - network environment of the clone's address.
+ * @returns the merge request URL the server printed, if any.
+ */
+export async function pushForMergeRequest(commands: GitCommands, dir: string, commit: string, branch: string, request: MergeRequestOptions, env: Readonly<Record<string, string>>): Promise<string | undefined> {
+  const options = [
+    'merge_request.create',
+    `merge_request.target=${request.target}`,
+    `merge_request.title=${oneLine(request.title)}`,
+    `merge_request.description=${oneLine(request.description)}`,
+  ].flatMap(option => ['-o', option])
+  const output = await commands.git(['push', '--porcelain', `--force-with-lease=refs/heads/${branch}:`, ...options, 'origin', `${commit}:refs/heads/${branch}`], { cwd: dir, timeoutMs: commands.timeoutMs, env, output: 'all' })
+  return /https?:\/\/\S+\/-\/merge_requests\/\d+/.exec(output)?.[0]
+}

package/src/skill-update/proposal.ts

@@ -0,0 +1,116 @@
+/**
+ * 子 Agent 写在运行目录里的 SKILL 修改提议：`skill-proposal/reason.md` 说明
+ * 理由，`skill-proposal/files/` 按相对路径存放应用 SKILL 目录
+ * `.dsh/skills/<skill>/` 下要新增或修改的完整文件。
+ *
+ * 运行目录对 Agent 可写，所以这里读到的一切都按不可信输入校验：只接受普通
+ * 文件和目录（不跟随符号链接）、受限的文件名、UTF-8 文本、文件数与大小上限。
+ *
+ * @module dsh-guanxiang/skill-update/proposal
+ */
+
+import { lstat, readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { disablesUserInvocation } from '../repos/manifest.ts'
+import type { SkillUpdateSettings } from '../settings/contract.ts'
+
+/** Proposal directory inside a task's run directory. */
+export const PROPOSAL_DIR = 'skill-proposal'
+
+/** Reason file inside {@link PROPOSAL_DIR}. */
+export const REASON_FILE = 'reason.md'
+
+/** Directory inside {@link PROPOSAL_DIR} mirroring `.dsh/skills/<skill>/`. */
+export const FILES_DIR = 'files'
+
+/** Diff the plugin writes next to the proposal, for the user to read. */
+export const DIFF_FILE = 'skill-proposal.diff'
+
+const SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/
+const decoder = new TextDecoder('utf-8', { fatal: true })
+
+/** A proposal that cannot be submitted, with a reason the model and user can act on. */
+export class ProposalError extends Error {}
+
+/** One file of a proposal, by its path relative to the skill directory. */
+export interface ProposedFile {
+  readonly path: string
+  readonly content: string
+}
+
+/** A validated proposal. */
+export interface Proposal {
+  readonly reason: string
+  readonly files: readonly ProposedFile[]
+}
+
+async function kindOf(path: string): Promise<'missing' | 'directory' | 'file' | 'other'> {
+  try {
+    const info = await lstat(path)
+    return info.isDirectory() ? 'directory' : info.isFile() ? 'file' : 'other'
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing'
+    throw error
+  }
+}
+
+async function readText(path: string, label: string, maxBytes: number): Promise<string> {
+  const info = await lstat(path)
+  if (info.size > maxBytes) throw new ProposalError(`${label} 有 ${info.size} 字节，超过上限 ${maxBytes}`)
+  const bytes = await readFile(path)
+  if (bytes.length > maxBytes) throw new ProposalError(`${label} 超过大小上限 ${maxBytes} 字节`)
+  let text: string
+  try {
+    text = decoder.decode(bytes)
+  } catch {
+    // TextDecoder reports only that the bytes are not UTF-8.
+    throw new ProposalError(`${label} 不是 UTF-8 文本`)
+  }
+  if (text.includes('\u0000')) throw new ProposalError(`${label} 包含 NUL 字符，不是文本文件`)
+  return text
+}
+
+/**
+ * Read and validate the proposal of one task.
+ * @param workDir - the task's run directory.
+ * @param limits - file count and size ceilings.
+ * @returns the proposal, or undefined when the task wrote none.
+ * @throws ProposalError when the proposal exists but cannot be submitted.
+ */
+export async function readProposal(workDir: string, limits: Pick<SkillUpdateSettings, 'maxFiles' | 'maxFileBytes'>): Promise<Proposal | undefined> {
+  const root = join(workDir, PROPOSAL_DIR)
+  const rootKind = await kindOf(root)
+  if (rootKind === 'missing') return undefined
+  if (rootKind !== 'directory') throw new ProposalError(`${PROPOSAL_DIR} 必须是目录`)
+
+  const reasonPath = join(root, REASON_FILE)
+  if (await kindOf(reasonPath) !== 'file') throw new ProposalError(`缺少 ${PROPOSAL_DIR}/${REASON_FILE}（修改理由）`)
+  const reason = (await readText(reasonPath, `${PROPOSAL_DIR}/${REASON_FILE}`, limits.maxFileBytes)).trim()
+  if (reason === '') throw new ProposalError(`${PROPOSAL_DIR}/${REASON_FILE} 不能为空`)
+
+  const filesRoot = join(root, FILES_DIR)
+  if (await kindOf(filesRoot) !== 'directory') throw new ProposalError(`缺少 ${PROPOSAL_DIR}/${FILES_DIR}/（修改后的 SKILL 文件）`)
+  const files: ProposedFile[] = []
+  const walk = async (dir: string, prefix: readonly string[]): Promise<void> => {
+    for (const entry of (await readdir(dir, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const segments = [...prefix, entry.name]
+      const relative = segments.join('/')
+      if (!SEGMENT.test(entry.name)) throw new ProposalError(`文件名不合法：${relative}（只允许字母、数字、. _ -，且不能以 . 或 - 开头）`)
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        await walk(path, segments)
+        continue
+      }
+      if (!entry.isFile()) throw new ProposalError(`${relative} 不是普通文件（不接受符号链接等）`)
+      if (files.length >= limits.maxFiles) throw new ProposalError(`文件数超过上限 ${limits.maxFiles}`)
+      files.push({ path: relative, content: await readText(path, relative, limits.maxFileBytes) })
+    }
+  }
+  await walk(filesRoot, [])
+  if (files.length === 0) throw new ProposalError(`${PROPOSAL_DIR}/${FILES_DIR}/ 中没有文件`)
+  const skill = files.find(file => file.path === 'SKILL.md')
+  if (skill !== undefined && disablesUserInvocation(skill.content)) {
+    throw new ProposalError('SKILL.md 不能设置 user-invocable: false，否则派发时无法用 /<skill> 加载')
+  }
+  return { reason, files }
+}

package/src/skill-update/tool.ts

@@ -0,0 +1,314 @@
+/**
+ * `guanxiang_propose_skill`：把某个派发任务的 SKILL 修改提议提交为合并请求。
+ *
+ * - 只接受本进程中由同一会话派发过的任务运行目录；应用、仓库和分析时的提交
+ *   取自派发记录，不取自运行目录里可被 Agent 改写的内容。
+ * - 只改应用 SKILL 目录 `.dsh/skills/<skill>/` 下的文件，提交以分析时的提交为
+ *   父提交，推送到新分支 `guanxiang/skill-<应用 id>-<树对象前缀>`，从不推送已有
+ *   分支或默认分支。
+ * - 推送前经 DSH 审批服务（`ctx.approval`）请求一次性授权；dsh_channels 把它
+ *   显示为飞书决策卡片，DSH Web 显示为审批提示。只有 `allowed-once` 才推送；
+ *   没有审批服务时工具报错，不推送。
+ * - 子会话中不提供本工具。
+ *
+ * @module dsh-guanxiang/skill-update/tool
+ */
+
+import { randomBytes } from 'node:crypto'
+import { rename, rm, writeFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { z } from 'zod'
+import { describeIssue } from '../config.ts'
+import { isDelegatedAgent } from '../dispatch/tool.ts'
+import type { ContentBlock, HostApproval, ToolDefinition, ToolRunContext } from '../host.ts'
+import type { GitRunner } from '../repos/git.ts'
+import type { RepoRegistry } from '../repos/registry.ts'
+import type { AppManifest, EditableSettings } from '../settings/contract.ts'
+import { commitChange, prepareChange, pushForMergeRequest, remoteBranchExists } from './git.ts'
+import type { CommitAuthor, FileStat, PreparedChange } from './git.ts'
+import { DIFF_FILE, FILES_DIR, PROPOSAL_DIR, ProposalError, readProposal, REASON_FILE } from './proposal.ts'
+
+/** Model-facing tool name. */
+export const PROPOSE_TOOL_NAME = 'guanxiang_propose_skill'
+
+/** Longest accepted one-line summary; it becomes the commit subject and merge request title. */
+export const MAX_SUMMARY_CHARS = 120
+
+/** Dispatched tasks remembered for submission; older ones are forgotten first. */
+const MAX_REMEMBERED_TASKS = 256
+
+/** Characters of the reason shown on an approval prompt. */
+const REASON_PREVIEW_CHARS = 300
+
+/** Characters of the reason sent as the merge request description; the commit message keeps all of it. */
+const REASON_DESCRIPTION_CHARS = 2000
+
+/** A dispatched task as the dispatch tool recorded it. */
+export interface DispatchedTask {
+  /** Absolute run directory of the task. */
+  readonly workDir: string
+  /** Session that dispatched the task. */
+  readonly sessionId: string
+  readonly app: AppManifest
+  /** Repository address the application came from. */
+  readonly url: string
+  /** Commit the child analyzed. */
+  readonly commit: string
+}
+
+/** A task's proposal as the dispatch result reports it. */
+export type ProposalCheck =
+  | { readonly ok: true; readonly files: readonly FileStat[]; readonly diffPath: string }
+  | { readonly ok: false; readonly error: string }
+
+/** How one submission ended. */
+export type ProposeStatus = 'opened' | 'pushed' | 'exists' | 'rejected' | 'cancelled' | 'unavailable'
+
+/** Canonical tool value. */
+export interface ProposeValue {
+  status: ProposeStatus
+  app: string
+  repo: string
+  /** New branch the change was or would be pushed to. */
+  branch: string
+  /** Branch the merge request targets. */
+  target: string
+  files: FileStat[]
+  /** Diff file in the task's run directory. */
+  diffPath: string
+  mergeRequestUrl?: string
+}
+
+const argsSchema = z.object({
+  workDir: z.string().trim().min(1, 'workDir 不能为空'),
+  summary: z.string().trim().min(1, 'summary 不能为空').max(MAX_SUMMARY_CHARS, `summary 不能超过 ${MAX_SUMMARY_CHARS} 个字符`)
+    .refine(value => !/[\r\n]/.test(value), 'summary 只能是一行'),
+}).strict()
+
+const PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['workDir', 'summary'],
+  properties: {
+    workDir: { type: 'string', description: '派发结果中带有 SKILL 修改提议的任务运行目录（绝对路径）。' },
+    summary: { type: 'string', description: `一句话说明改了什么，用作提交标题和合并请求标题，不超过 ${MAX_SUMMARY_CHARS} 个字符。` },
+  },
+}
+
+const FILE_STAT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['path'],
+  properties: { path: { type: 'string' }, added: { type: 'number' }, removed: { type: 'number' } },
+} as const
+
+const OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['status', 'app', 'repo', 'branch', 'target', 'files', 'diffPath'],
+  properties: {
+    status: { type: 'string', enum: ['opened', 'pushed', 'exists', 'rejected', 'cancelled', 'unavailable'] },
+    app: { type: 'string' },
+    repo: { type: 'string' },
+    branch: { type: 'string' },
+    target: { type: 'string' },
+    files: { type: 'array', items: FILE_STAT_SCHEMA },
+    diffPath: { type: 'string' },
+    mergeRequestUrl: { type: 'string' },
+  },
+} as const
+
+/**
+ * Render line counts as `path（+a −r）`, separated by `、`.
+ * @param files - changed files.
+ * @returns one line.
+ */
+export function describeFiles(files: readonly FileStat[]): string {
+  return files.map(file => file.added === undefined ? `${file.path}（二进制）` : `${file.path}（+${file.added} −${file.removed ?? 0}）`).join('、')
+}
+
+/**
+ * Model-facing rendering of a submission.
+ * @param value - canonical value.
+ * @returns text content.
+ */
+export function renderProposeValue(value: ProposeValue): ContentBlock[] {
+  const where = `${value.repo} 的分支 ${value.branch}（目标 ${value.target}）`
+  const text = {
+    opened: `已推送到 ${where} 并创建合并请求：${value.mergeRequestUrl ?? ''}`,
+    pushed: `已推送到 ${where}，但服务器没有返回合并请求链接；请在 GitLab 上确认合并请求是否已创建。`,
+    exists: `${where} 已存在，同一改动可能已经提交过，本次没有推送。`,
+    rejected: '授权被拒绝，没有推送：用户拒绝了这次修改，或会话的审批策略为 never（例如「完全访问」权限模式）。',
+    cancelled: '授权请求被撤回，没有推送。',
+    unavailable: '当前没有可以回答授权请求的界面，没有推送。',
+  }[value.status]
+  return [{ type: 'text', text: `${text}\n改动：${describeFiles(value.files)}\ndiff：${value.diffPath}` }]
+}
+
+/** Collaborators of the submission tool. */
+export interface SkillUpdaterDeps {
+  readonly registry: RepoRegistry
+  settings(): EditableSettings
+  readonly git: GitRunner
+  readonly gitTimeoutMs: number
+  readonly author?: CommitAuthor
+  /** DSH's approval service, when the composition has one. */
+  approval(): HostApproval | undefined
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Write a file in an agent-writable directory without following whatever
+ * entry the agent left at its path: the content goes to a new file created
+ * exclusively, which then replaces the directory entry.
+ */
+async function replaceFile(path: string, content: string): Promise<void> {
+  const temporary = `${path}.${randomBytes(6).toString('hex')}.tmp`
+  try {
+    await writeFile(temporary, content, { flag: 'wx' })
+    await rename(temporary, path)
+  } catch (error) {
+    await rm(temporary, { force: true })
+    throw error
+  }
+}
+
+function skillDirOf(app: AppManifest): string {
+  return `.dsh/skills/${app.skill}`
+}
+
+/** Remembers dispatched tasks, checks their proposals, and submits them. */
+export class SkillUpdater {
+  private readonly tasks = new Map<string, DispatchedTask>()
+
+  /** @param deps - registry, settings, git, and approval access. */
+  constructor(private readonly deps: SkillUpdaterDeps) {}
+
+  /** @returns whether proposals are enabled in the current settings. */
+  enabled(): boolean {
+    return this.deps.settings().skillUpdates.enabled
+  }
+
+  /**
+   * Remember a finished task and check the proposal it wrote, writing the
+   * diff next to it.
+   * @param task - the dispatched task.
+   * @returns the check, or undefined when the task wrote no proposal.
+   */
+  async inspect(task: DispatchedTask): Promise<ProposalCheck | undefined> {
+    this.remember(task)
+    try {
+      const prepared = await this.prepare(task)
+      if (prepared === undefined) return undefined
+      return { ok: true, files: prepared.change.files, diffPath: prepared.diffPath }
+    } catch (error) {
+      return { ok: false, error: messageOf(error) }
+    }
+  }
+
+  private remember(task: DispatchedTask): void {
+    this.tasks.delete(task.workDir)
+    this.tasks.set(task.workDir, task)
+    for (const key of this.tasks.keys()) {
+      if (this.tasks.size <= MAX_REMEMBERED_TASKS) break
+      this.tasks.delete(key)
+    }
+  }
+
+  /**
+   * Read the proposal, build its tree, and write the diff file.
+   * @returns undefined when the task wrote no proposal.
+   * @throws ProposalError or a git failure.
+   */
+  private async prepare(task: DispatchedTask): Promise<{ reason: string; change: PreparedChange; target: string; diffPath: string } | undefined> {
+    const proposal = await readProposal(task.workDir, this.deps.settings().skillUpdates)
+    if (proposal === undefined) return undefined
+    const commands = { git: this.deps.git, timeoutMs: this.deps.gitTimeoutMs }
+    const { change, target } = await this.deps.registry.withClone(task.url, async clone => ({
+      change: await prepareChange(commands, clone.dir, task.commit, skillDirOf(task.app), proposal.files),
+      target: clone.branch,
+    }))
+    if (change.files.length === 0) throw new ProposalError(`提议的文件与提交 ${task.commit.slice(0, 12)} 中的 SKILL 相同，没有改动`)
+    const diffPath = join(task.workDir, DIFF_FILE)
+    await replaceFile(diffPath, change.diff)
+    return { reason: proposal.reason, change, target, diffPath }
+  }
+
+  /**
+   * Build the tool definition.
+   * @returns the registration.
+   */
+  definition(): ToolDefinition<ProposeValue> {
+    return {
+      name: PROPOSE_TOOL_NAME,
+      description: '观象：把派发结果中某个应用的 SKILL 修改提议提交为合并请求。工具先请求用户授权，批准后推送新分支并创建合并请求，不会直接改动默认分支。'
+        + '仅在派发结果标出了 SKILL 修改提议时使用；不要自己用 git 推送。',
+      parameters: PARAMETERS,
+      output: {
+        schema: OUTPUT_SCHEMA,
+        render: (_args, value) => renderProposeValue(value),
+      },
+      isConcurrencySafe: () => false,
+      execute: (args, exec) => this.execute(args, exec),
+    }
+  }
+
+  /**
+   * Submit one proposal.
+   * @param rawArgs - model arguments.
+   * @param exec - execution context of the calling agent.
+   * @returns how the submission ended.
+   * @throws when the arguments, task, proposal, or approval service are unusable, or git fails; nothing is pushed then.
+   */
+  async execute(rawArgs: unknown, exec: ToolRunContext): Promise<ProposeValue> {
+    const parsed = argsSchema.safeParse(rawArgs)
+    if (!parsed.success) throw new Error(`${PROPOSE_TOOL_NAME} 参数不合法：${describeIssue(parsed.error)}`)
+    const { summary } = parsed.data
+    const agent = exec.agent
+    if (agent === undefined) throw new Error(`${PROPOSE_TOOL_NAME} 需要由 Agent 调用`)
+    if (isDelegatedAgent(agent)) throw new Error(`${PROPOSE_TOOL_NAME} 不能在子 Agent 中调用`)
+    if (!this.enabled()) throw new Error('观象的 SKILL 修改提议未开启（设置面板「高级」→「SKILL 改进」）')
+    const task = this.tasks.get(resolve(parsed.data.workDir))
+    if (task === undefined) throw new Error(`${parsed.data.workDir} 不是本次 DSH 运行中观象派发任务的运行目录；DSH 重启后需要重新分析`)
+    if (task.sessionId !== agent.session.header.id) throw new Error(`${parsed.data.workDir} 不是当前会话派发的任务`)
+    const approval = this.deps.approval()
+    if (approval === undefined) throw new Error('当前 DSH 组合没有审批服务（@deepseek-ai/dsh-user-approval），观象不会在未经授权时推送')
+
+    const prepared = await this.prepare(task)
+    if (prepared === undefined) throw new Error(`${task.workDir} 中没有 SKILL 修改提议（${PROPOSAL_DIR}/${REASON_FILE} 与 ${PROPOSAL_DIR}/${FILES_DIR}/）`)
+    const { change, target, diffPath, reason } = prepared
+    const branch = `guanxiang/skill-${task.app.id}-${change.tree.slice(0, 10)}`
+    const base = { app: task.app.id, repo: task.url, branch, target, files: [...change.files], diffPath }
+    const commands = { git: this.deps.git, timeoutMs: this.deps.gitTimeoutMs }
+
+    if (await this.deps.registry.withClone(task.url, clone => remoteBranchExists(commands, clone.dir, branch, clone.env))) {
+      return { ...base, status: 'exists' }
+    }
+
+    const preview = reason.replace(/\s+/g, ' ').slice(0, REASON_PREVIEW_CHARS)
+    const zh = `观象将向 ${task.url} 推送新分支 ${branch}，并创建合并请求合入 ${target}。改动：${describeFiles(change.files)}。摘要：${summary}。理由：${preview}`
+    const en = `GuanXiang will push branch ${branch} to ${task.url} and open a merge request into ${target}. Files: ${change.files.map(file => file.path).join(', ')}. Summary: ${summary}`
+    const outcome = await approval.request({
+      agent,
+      toolName: PROPOSE_TOOL_NAME,
+      ...exec.callId === undefined ? {} : { callId: exec.callId },
+      reason: zh,
+      displayReason: { en, zh },
+      signal: exec.signal,
+    })
+    if (outcome === 'cancelled') exec.signal.throwIfAborted()
+    if (outcome !== 'allowed-once') return { ...base, status: outcome }
+
+    const message = `${summary}\n\n${reason}\n\nProposed-by: 观象 GuanXiang\nAnalyzed-commit: ${task.commit}\nSession: ${task.sessionId}\n`
+    const description = `由观象在日志分析中提出（应用 ${task.app.id}，分析提交 ${task.commit.slice(0, 12)}，会话 ${task.sessionId}）。理由：${reason.slice(0, REASON_DESCRIPTION_CHARS)}`
+    const url = await this.deps.registry.withClone(task.url, async (clone) => {
+      exec.signal.throwIfAborted()
+      const commit = await commitChange(commands, clone.dir, change, message, this.deps.author)
+      return await pushForMergeRequest(commands, clone.dir, commit, branch, { target, title: summary, description }, clone.env)
+    })
+    return url === undefined ? { ...base, status: 'pushed' } : { ...base, status: 'opened', mergeRequestUrl: url }
+  }
+}