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

package/src/service.ts

@@ -5,20 +5,19 @@
  * @module dsh-guanxiang/service
  */
 
+import type { DshRepoService } from 'dsh-repo/contract'
 import { z } from 'zod'
-import { applyOverlay, defaultsOf, describeIssue, editableSettingsSchema, expandHome } from './config.ts'
-import type { GuanxiangConfig, SettingsOverlay } from './config.ts'
+import { applyOverlay, defaultsOf, describeIssue, editableSettingsSchema } from './config.ts'
+import type { GuanxiangConfig, LegacyCredential, SettingsOverlay } from './config.ts'
 import { abortable } from './abort.ts'
 import type { AnalyzeGate } from './analyze/server.ts'
 import { FEISHU_TOPICS_SERVICE, lookupTopics } from './analyze/topics.ts'
 import { Dispatcher, isDelegatedAgent, isInside } from './dispatch/tool.ts'
 import type { HostApproval, HostContext, HostCredentials, ToolActivationContext, WorkingDirectoryService } from './host.ts'
-import { credentialEnvironment, credentialFor, isAcceptedToken, MAX_TOKEN_LENGTH } from './repos/credentials.ts'
-import { runGit } from './repos/git.ts'
-import type { GitRunner } from './repos/git.ts'
+import { DSH_REPOS_SERVICE, lookupRepos, messageOf, repoErrorCode, unavailableMessage } from './repos/lookup.ts'
 import { RepoRegistry } from './repos/registry.ts'
 import { ANALYZE_ROUTE } from './settings/contract.ts'
-import type { AnalyzeWire, CredentialsWire, EditableSettings, StateWire, TokenStatusWire } from './settings/contract.ts'
+import type { AnalyzeWire, EditableSettings, HostsWire, StateWire, TokenStatusWire } from './settings/contract.ts'
 import { diffOverlay, overriddenKeys } from './settings/overlay.ts'
 import type { OverlayStore } from './settings/overlay.ts'
 import { createEntrySkillProvider } from './skill/entry.ts'
@@ -27,14 +26,24 @@ import { SkillUpdater } from './skill-update/tool.ts'
 /** A settings write the panel reports as a field error. */
 export class SettingsError extends Error {}
 
+/** Longest accepted token; personal access tokens are far shorter. */
+const MAX_TOKEN_LENGTH = 4096
+
+const tokenValue = z.string().trim()
+  .refine(value => value.length > 0 && value.length <= MAX_TOKEN_LENGTH && !/[\u0000-\u001f\u007f]/.test(value), `令牌不能为空、超过 ${MAX_TOKEN_LENGTH} 个字符或包含换行等控制字符`)
 const tokenClearSchema = z.object({ tokenEnv: z.string() }).strict()
-const tokenSetSchema = tokenClearSchema.extend({
-  value: z.string().trim().refine(isAcceptedToken, `令牌不能为空、超过 ${MAX_TOKEN_LENGTH} 个字符或包含换行等控制字符`),
+const tokenSetSchema = tokenClearSchema.extend({ value: tokenValue }).strict()
+const hostUrlSchema = z.object({ url: z.string().trim().min(1, '主机地址不能为空') }).strict()
+const hostTokenSchema = hostUrlSchema.extend({ value: tokenValue }).strict()
+const hostAddSchema = z.object({
+  kind: z.enum(['github', 'gitlab']).optional(),
+  url: z.string().trim().min(1, '主机地址不能为空'),
+  alias: z.string().trim().max(64, '别名不能超过 64 个字符').optional().transform(value => value === '' ? undefined : value),
+  token: tokenValue.optional(),
 }).strict()
 
 /** Optional seams for tests. */
 export interface ServiceOptions {
-  readonly git?: GitRunner
   readonly fetch?: typeof fetch
 }
 
@@ -51,6 +60,7 @@ export class GuanxiangService {
   private active = true
   private readonly refreshWaitMs: number
   private readonly analyzeTokenRef: string
+  private readonly legacyCredentials: readonly LegacyCredential[]
   private readonly booted = Promise.withResolvers<void>()
 
   /**
@@ -68,21 +78,18 @@ export class GuanxiangService {
     this.defaults = defaultsOf(config)
     this.refreshWaitMs = config.refreshWaitMs
     this.analyzeTokenRef = config.analyzeTokenRef
+    this.legacyCredentials = config.gitCredentials
     this.current = this.defaults
-    const git = options.git ?? runGit
     this.registry = new RepoRegistry({
-      git,
-      gitTimeoutMs: config.gitTimeoutMs,
-      auth: url => this.gitAuth(url),
+      repos: () => ctx.get?.(DSH_REPOS_SERVICE),
       onChange: () => { this.onRegistryChange() },
     })
     this.updater = new SkillUpdater({
       registry: this.registry,
       settings: () => this.current,
-      git,
-      gitTimeoutMs: config.gitTimeoutMs,
       ...config.skillUpdateAuthor === undefined ? {} : { author: config.skillUpdateAuthor },
       approval: () => ctx.get?.('approval') as HostApproval | undefined,
+      repos: () => ctx.get?.(DSH_REPOS_SERVICE),
     })
     this.dispatcher = new Dispatcher({
       registry: this.registry,
@@ -99,7 +106,10 @@ export class GuanxiangService {
       maxAppsPerRequest: () => this.current.maxAppsPerRequest,
       skillUpdates: () => this.current.skillUpdates.enabled,
       autoInvoke: config.autoInvoke,
-      inRepositories: cwd => isInside(cwd, expandHome(this.current.reposDir)),
+      inRepositories: (cwd) => {
+        const lookup = lookupRepos(ctx.get?.(DSH_REPOS_SERVICE))
+        return lookup.availability === 'ready' && isInside(cwd, lookup.service.mirrorSettings().dir)
+      },
     })
   }
 
@@ -156,7 +166,8 @@ export class GuanxiangService {
   }
 
   /**
-   * Load the panel overlay, configure the registry, and sync every repository.
+   * Load the panel overlay, configure the registry, move legacy access tokens
+   * to dsh-repo hosts, and sync every repository.
    * @returns when the first sync round settled.
    */
   async boot(): Promise<void> {
@@ -176,10 +187,54 @@ export class GuanxiangService {
       this.ctx.logger?.warn?.('guanxiang: 忽略面板设置：%s', read.error)
     }
     this.current = applyOverlay(this.defaults, this.overlay)
-    this.registry.configure(this.current.reposDir, this.current.repos)
+    this.registry.configure(this.current.repos)
+    await this.migrateCredentials()
     await this.registry.syncAll()
   }
 
+  /**
+   * React to dsh-repo becoming available (or reloading): move legacy tokens
+   * and sync every repository again.
+   * @returns when the syncs settled.
+   */
+  async reposAvailable(): Promise<void> {
+    await this.booted.promise
+    if (!this.active) return
+    await this.migrateCredentials()
+    await this.registry.resyncAll()
+  }
+
+  /**
+   * Add each access token of earlier versions whose address dsh-repo does not
+   * know yet as a dsh-repo host, carrying the stored token value. The panel's
+   * list replaces the cordis.yml list, as it did before. An entry whose token
+   * cannot be resolved yet is left for a later start instead of creating a
+   * host without a token. Failures are logged; the legacy entry stays and the
+   * next start tries again.
+   */
+  private async migrateCredentials(): Promise<void> {
+    const legacy = this.overlay.gitCredentials ?? this.legacyCredentials
+    if (legacy.length === 0) return
+    const lookup = lookupRepos(this.ctx.get?.(DSH_REPOS_SERVICE))
+    if (lookup.availability !== 'ready') return
+    const store = this.credentialStore()
+    if (store === undefined) return
+    for (const credential of legacy) {
+      try {
+        const token = (await store.resolve(credential.tokenEnv))?.value
+        if (token === undefined || token === '') {
+          this.ctx.logger?.warn?.('guanxiang: 访问令牌 %s 尚未设置，暂不迁移到 dsh-repo', credential.url)
+          continue
+        }
+        await lookup.service.addHost({ url: credential.url, ...credential.alias === undefined || credential.alias === '' ? {} : { alias: credential.alias }, token })
+        this.ctx.logger?.info?.('guanxiang: 已把访问令牌 %s 迁移为 dsh-repo 主机', credential.url)
+      } catch (error) {
+        if (repoErrorCode(error) === 'conflict') continue
+        this.ctx.logger?.warn?.('guanxiang: 迁移访问令牌 %s 到 dsh-repo 失败：%s', credential.url, messageOf(error))
+      }
+    }
+  }
+
   /** Stop registering tools; in-flight syncs finish without side effects on the host. */
   shutdown(): void {
     this.active = false
@@ -199,7 +254,8 @@ export class GuanxiangService {
       overridden: overriddenKeys(this.overlay),
       ...this.overlayError === undefined ? {} : { overlayError: this.overlayError },
       repos: this.registry.status(),
-      credentials: await this.credentialsState(),
+      hosts: await this.hostsState(),
+      credentialsAvailable: this.credentialStore() !== undefined,
       analyze: await this.analyzeState(),
     }
   }
@@ -234,39 +290,100 @@ export class GuanxiangService {
     return this.ctx.get?.('credentials') as HostCredentials | undefined
   }
 
-  private async credentialsState(): Promise<CredentialsWire> {
-    const store = this.credentialStore()
-    if (store === undefined) return { available: false, tokens: [] }
-    const names = [...new Set(this.current.gitCredentials.map(credential => credential.tokenEnv))]
-    const tokens = await Promise.all(names.map(tokenEnv => describeToken(store, tokenEnv)))
-    return { available: true, tokens }
+  private async hostsState(): Promise<HostsWire> {
+    const lookup = lookupRepos(this.ctx.get?.(DSH_REPOS_SERVICE))
+    if (lookup.availability !== 'ready') return { availability: lookup.availability, hosts: [] }
+    const mirrorDir = lookup.service.mirrorSettings().dir
+    try {
+      const hosts = await lookup.service.listHosts()
+      return {
+        availability: 'ready',
+        mirrorDir,
+        hosts: hosts.map(host => ({
+          kind: host.kind,
+          url: host.url,
+          ...host.alias === undefined ? {} : { alias: host.alias },
+          origin: host.origin,
+          token: { tokenEnv: host.tokenRef, ...host.token },
+        })),
+      }
+    } catch (error) {
+      return { availability: 'ready', mirrorDir, hosts: [], error: messageOf(error) }
+    }
   }
 
   /**
-   * Environment carrying the access token for one repository address; empty
-   * when no access-token configuration matches it.
-   * @param url - repository address.
-   * @returns variables for its network git commands.
-   * @throws when a configuration matches but its token cannot be read.
+   * Add a dsh-repo host, optionally with its token, then sync every repository.
+   * @param raw - request body `{ kind?, url, alias?, token? }`.
+   * @returns the new panel state.
+   * @throws SettingsError when the body is invalid, dsh-repo is unavailable, or it refuses the host.
    */
-  private async gitAuth(url: string): Promise<Record<string, string>> {
-    const spec = credentialFor(url, this.current.gitCredentials)
-    if (spec === undefined) return {}
-    const store = this.credentialStore()
-    if (store === undefined) throw new Error(`地址匹配访问令牌 ${spec.url}，但当前 DSH 组合没有凭据服务，无法读取 ${spec.tokenEnv}`)
-    const token = await store.resolve(spec.tokenEnv)
-    if (token === undefined) throw new Error(`地址匹配访问令牌 ${spec.url}，但 ${spec.tokenEnv} 未设置：请在观象面板「访问令牌」中保存令牌，或设置同名环境变量`)
-    if (!isAcceptedToken(token.value)) throw new Error(`${spec.tokenEnv} 的值不能用作令牌：不能超过 ${MAX_TOKEN_LENGTH} 个字符或包含换行等控制字符`)
-    return credentialEnvironment(spec, token.value)
+  async addHost(raw: unknown): Promise<StateWire> {
+    const parsed = hostAddSchema.safeParse(raw)
+    if (!parsed.success) throw new SettingsError(describeIssue(parsed.error))
+    const { kind, url, alias, token } = parsed.data
+    await this.withRepos(repos => repos.addHost({ url, ...kind === undefined ? {} : { kind }, ...alias === undefined ? {} : { alias }, ...token === undefined ? {} : { token } }))
+    return await this.state()
+  }
+
+  /**
+   * Remove a host added from a panel, and its stored token.
+   * @param raw - request body `{ url }`.
+   * @returns the new panel state.
+   * @throws SettingsError when the body is invalid, dsh-repo is unavailable, or the host is unknown or configured in cordis.yml.
+   */
+  async removeHost(raw: unknown): Promise<StateWire> {
+    const parsed = hostUrlSchema.safeParse(raw)
+    if (!parsed.success) throw new SettingsError(describeIssue(parsed.error))
+    await this.withRepos(repos => repos.removeHost(parsed.data.url))
+    return await this.state()
   }
 
   /**
-   * Store the token of one access-token configuration in DSH's credential
-   * store, then re-sync the repositories that use it; or store the analyze
-   * API's bearer token (`analyzeTokenRef`), which applies from the next request.
+   * Store a host's token through dsh-repo, then sync every repository.
+   * @param raw - request body `{ url, value }`.
+   * @returns the new panel state.
+   * @throws SettingsError when the body is invalid, dsh-repo is unavailable, or the host is unknown.
+   */
+  async setHostToken(raw: unknown): Promise<StateWire> {
+    const parsed = hostTokenSchema.safeParse(raw)
+    if (!parsed.success) throw new SettingsError(describeIssue(parsed.error))
+    await this.withRepos(repos => repos.setHostToken(parsed.data.url, parsed.data.value))
+    return await this.state()
+  }
+
+  /**
+   * Remove a host's stored token; an environment variable of the same name applies again.
+   * @param raw - request body `{ url }`.
+   * @returns the new panel state.
+   * @throws SettingsError on the same conditions as {@link setHostToken}.
+   */
+  async clearHostToken(raw: unknown): Promise<StateWire> {
+    const parsed = hostUrlSchema.safeParse(raw)
+    if (!parsed.success) throw new SettingsError(describeIssue(parsed.error))
+    await this.withRepos(repos => repos.setHostToken(parsed.data.url, undefined))
+    return await this.state()
+  }
+
+  /** Run one host change and start a resync, reporting dsh-repo failures as field errors. */
+  private async withRepos(change: (repos: DshRepoService) => Promise<unknown>): Promise<void> {
+    const lookup = lookupRepos(this.ctx.get?.(DSH_REPOS_SERVICE))
+    if (lookup.availability !== 'ready') throw new SettingsError(unavailableMessage(lookup.availability))
+    try {
+      await change(lookup.service)
+    } catch (error) {
+      if (repoErrorCode(error) !== undefined) throw new SettingsError(messageOf(error))
+      throw error
+    }
+    void this.registry.resyncAll()
+  }
+
+  /**
+   * Store the analyze API's bearer token (`analyzeTokenRef`) in DSH's
+   * credential store; it applies from the next request.
    * @param raw - request body `{ tokenEnv, value }`.
    * @returns the new panel state.
-   * @throws SettingsError when the body is invalid, the name is neither referenced by the saved settings nor `analyzeTokenRef`, or no credential store is loaded.
+   * @throws SettingsError when the body is invalid, the name is not `analyzeTokenRef`, or no credential store is loaded.
    */
   async setToken(raw: unknown): Promise<StateWire> {
     const parsed = tokenSetSchema.safeParse(raw)
@@ -275,8 +392,8 @@ export class GuanxiangService {
   }
 
   /**
-   * Remove the stored token of one access-token configuration; an environment
-   * variable of the same name applies again afterwards.
+   * Remove the stored analyze token; an environment variable of the same name
+   * applies again afterwards.
    * @param raw - request body `{ tokenEnv }`.
    * @returns the new panel state.
    * @throws SettingsError on the same conditions as {@link setToken}.
@@ -288,18 +405,17 @@ export class GuanxiangService {
   }
 
   private async writeToken(tokenEnv: string, value: string | undefined): Promise<StateWire> {
-    if (tokenEnv !== this.analyzeTokenRef && !this.current.gitCredentials.some(credential => credential.tokenEnv === tokenEnv)) throw new SettingsError(`${tokenEnv} 不是已保存的访问令牌配置引用的名称`)
+    if (tokenEnv !== this.analyzeTokenRef) throw new SettingsError(`${tokenEnv} 不是分析接口令牌的名称`)
     const store = this.credentialStore()
     if (store === undefined) throw new SettingsError('当前 DSH 组合没有凭据服务（@deepseek-ai/dsh-credentials-local），无法保存令牌')
     if (value === undefined) await store.unset(tokenEnv)
     else await store.set(tokenEnv, value)
-    void this.registry.resyncUrls(this.current.repos.map(repo => repo.url).filter(url => credentialFor(url, this.current.gitCredentials)?.tokenEnv === tokenEnv))
     return await this.state()
   }
 
   /**
    * Validate and persist a complete settings payload from the panel, then
-   * sync repositories whose address, branch, or directory changed.
+   * sync repositories whose address or branch changed.
    * @param raw - request body.
    * @returns the new panel state.
    * @throws SettingsError when the payload is invalid.
@@ -333,21 +449,12 @@ export class GuanxiangService {
     void (url === undefined ? this.registry.syncAll() : this.registry.syncUrls([url]))
   }
 
-  /**
-   * Make an overlay effective and sync the repositories whose address, branch,
-   * directory, or matching access-token configuration changed.
-   */
+  /** Make an overlay effective and sync the repositories whose address or branch changed. */
   private apply(overlay: SettingsOverlay): void {
-    const previous = this.current.gitCredentials
     this.overlay = overlay
     this.overlayError = undefined
     this.current = applyOverlay(this.defaults, overlay)
-    const changed = this.registry.configure(this.current.reposDir, this.current.repos)
-    const next = this.current.gitCredentials
-    const reauthorized = this.current.repos.map(repo => repo.url)
-      .filter(url => JSON.stringify(credentialFor(url, previous)) !== JSON.stringify(credentialFor(url, next)))
-    void this.registry.syncUrls(changed)
-    void this.registry.resyncUrls(reauthorized.filter(url => !changed.includes(url)))
+    void this.registry.syncUrls(this.registry.configure(this.current.repos))
   }
 
   private onRegistryChange(): void {

package/src/settings/contract.ts

@@ -11,8 +11,12 @@ export const STATE_ROUTE = '/guanxiang/state'
 export const SETTINGS_ROUTE = '/guanxiang/settings'
 /** POST：立即重新拉取全部仓库，或 body `{ url }` 指定的一个仓库。 */
 export const SYNC_ROUTE = '/guanxiang/sync'
-/** PUT：body `{ tokenEnv, value }` 把令牌存入 DSH 凭据库；DELETE：body `{ tokenEnv }` 删除已存的值。只接受已保存的访问令牌配置引用的名称和分析接口令牌的名称。 */
+/** PUT：body `{ tokenEnv, value }` 把分析接口令牌存入 DSH 凭据库；DELETE：body `{ tokenEnv }` 删除已存的值。只接受分析接口令牌的名称。 */
 export const TOKEN_ROUTE = '/guanxiang/token'
+/** POST：body {@link HostAddRequest} 经 dsh-repo 添加主机；DELETE：body `{ url }` 删除面板添加的主机。 */
+export const HOSTS_ROUTE = '/guanxiang/hosts'
+/** PUT：body `{ url, value }` 经 dsh-repo 保存主机令牌；DELETE：body `{ url }` 清除已存的令牌。 */
+export const HOST_TOKEN_ROUTE = '/guanxiang/host-token'
 
 /**
  * POST：日志平台分析接口（Bearer 令牌鉴权，不走 DSH 登录）。它在 DSH 的
@@ -22,25 +26,27 @@ export const ANALYZE_ROUTE = '/open-api/logalyze'
 
 /** One configured application repository. */
 export interface RepoSpec {
-  /** Git remote address, cloned with the host machine's existing git credentials or a matching {@link GitCredentialSpec}. */
+  /** Git remote address, mirrored by dsh-repo with the token of its host or the machine's existing git credentials. */
   url: string
   /** Remote branch to follow; omitted follows the remote's default branch. */
   branch?: string
 }
 
-/** Credential reference grammar of `@deepseek-ai/dsh-credentials` (a POSIX shell identifier), which {@link GitCredentialSpec.tokenEnv} follows. */
+/** Credential reference grammar of `@deepseek-ai/dsh-credentials` (a POSIX shell identifier). */
 export const TOKEN_ENV_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
 
-/** HTTPS access token used for the repositories under one address prefix. */
-export interface GitCredentialSpec {
-  /** `https://host[:port][/path]` (or `http://`) prefix; repository addresses under it use this token. */
+/** Code host family of a dsh-repo host. */
+export type HostKind = 'github' | 'gitlab'
+
+/** Body of a {@link HOSTS_ROUTE} POST. */
+export interface HostAddRequest {
+  /** Default `gitlab`. */
+  kind?: HostKind
+  /** `https://host[:port][/path]`. */
   url: string
-  /** Display name the panel shows for this token; omitted shows the address. */
   alias?: string
-  /** HTTP username sent with the token; GitLab personal access tokens accept `oauth2`. */
-  username: string
-  /** Credential reference (environment-variable name) whose value in DSH's credential store is the token. */
-  tokenEnv: string
+  /** Token value; omitted leaves it unset. */
+  token?: string
 }
 
 /** Log URL download policy. */
@@ -71,12 +77,8 @@ export interface AnalyzeSettings {
 
 /** The settings the Web panel can override; every field is required on the wire. */
 export interface EditableSettings {
-  /** Absolute directory holding the cloned repositories (`~` expands to the home directory). */
-  reposDir: string
-  /** Application repositories to clone and keep updated. */
+  /** Application repositories to mirror and keep updated. */
   repos: RepoSpec[]
-  /** HTTPS access tokens by address prefix; the token values stay in DSH's credential store. */
-  gitCredentials: GitCredentialSpec[]
   /** Minimum age of a repository's last sync before loading `/guanxiang` syncs it again, in milliseconds; 0 syncs on every load. */
   fetchIntervalMs: number
   /** Maximum number of child analyses one dispatch may start. */
@@ -92,7 +94,7 @@ export interface EditableSettings {
 }
 
 /** Keys of {@link EditableSettings}, in panel order. */
-export const EDITABLE_KEYS = ['reposDir', 'repos', 'gitCredentials', 'fetchIntervalMs', 'maxAppsPerRequest', 'dispatchTimeoutMs', 'download', 'skillUpdates', 'analyze'] as const satisfies readonly (keyof EditableSettings)[]
+export const EDITABLE_KEYS = ['repos', 'fetchIntervalMs', 'maxAppsPerRequest', 'dispatchTimeoutMs', 'download', 'skillUpdates', 'analyze'] as const satisfies readonly (keyof EditableSettings)[]
 
 /** One editable key. */
 export type EditableKey = (typeof EDITABLE_KEYS)[number]
@@ -120,8 +122,8 @@ export type RepoPhase = 'pending' | 'syncing' | 'ready' | 'failed'
 export interface RepoStatusWire {
   url: string
   branch?: string
-  /** Absolute directory of the fetch-only clone; children work in commit snapshots under `<reposDir>/.snapshots/`. */
-  dir: string
+  /** Absolute directory of dsh-repo's fetch-only mirror, once a sync succeeded; children work in commit snapshots dsh-repo creates. */
+  dir?: string
   phase: RepoPhase
   /** Latest synced commit, the one the catalog describes and new dispatches use. */
   commit?: string
@@ -152,12 +154,32 @@ export interface TokenStatusWire {
   error?: string
 }
 
-/** Credential store view of the panel. */
-export interface CredentialsWire {
-  /** Whether the DSH composition provides `ctx.credentials`; without it tokens cannot be stored or read. */
-  available: boolean
-  /** One entry per distinct `tokenEnv` of the effective settings; empty while unavailable. */
-  tokens: TokenStatusWire[]
+/** One dsh-repo host as the panel shows it. */
+export interface HostWire {
+  kind: HostKind
+  url: string
+  alias?: string
+  /** `config`: from dsh-repo's cordis.yml entry, not removable here; `added`: added from a panel. */
+  origin: 'config' | 'added'
+  token: TokenStatusWire
+}
+
+/**
+ * Whether dsh-repo provides the `dshRepos` service this plugin mirrors
+ * repositories and submits proposals through: `missing` while it is not
+ * loaded, `incompatible` when it is too old.
+ */
+export type ReposAvailability = 'ready' | 'missing' | 'incompatible'
+
+/** dsh-repo view of the panel. */
+export interface HostsWire {
+  availability: ReposAvailability
+  /** Configured hosts first; empty unless `ready`. */
+  hosts: HostWire[]
+  /** Mirror directory; absent unless `ready`. */
+  mirrorDir?: string
+  /** Why the hosts could not be listed. */
+  error?: string
 }
 
 /**
@@ -190,7 +212,9 @@ export interface StateWire {
   /** Why the overlay file was ignored (unreadable or invalid); panel saves replace it. */
   overlayError?: string
   repos: RepoStatusWire[]
-  credentials: CredentialsWire
+  hosts: HostsWire
+  /** Whether the DSH composition provides `ctx.credentials`; without it the analyze token cannot be stored or read. */
+  credentialsAvailable: boolean
   analyze: AnalyzeWire
 }
 

package/src/settings/routes.ts

@@ -10,7 +10,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { HostContext, HostRequestGate, HostWebServer } from '../host.ts'
 import { SettingsError } from '../service.ts'
 import type { GuanxiangService } from '../service.ts'
-import { SETTINGS_ROUTE, STATE_ROUTE, SYNC_ROUTE, TOKEN_ROUTE } from './contract.ts'
+import { HOST_TOKEN_ROUTE, HOSTS_ROUTE, SETTINGS_ROUTE, STATE_ROUTE, SYNC_ROUTE, TOKEN_ROUTE } from './contract.ts'
 
 type WebHandler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
 
@@ -151,6 +151,24 @@ export function registerSettingsRoutes(server: HostWebServer, gate: HostRequestG
         sendJson(res, 200, { ok: true, state })
       }),
     }),
+    server.register({
+      kind: 'exact',
+      path: HOSTS_ROUTE,
+      handler: guarded(gate, ['POST', 'DELETE'], async (req, res) => {
+        const body = await readJsonBody(req, false)
+        const state = req.method?.toUpperCase() === 'DELETE' ? await service.removeHost(body) : await service.addHost(body)
+        sendJson(res, 200, { ok: true, state })
+      }),
+    }),
+    server.register({
+      kind: 'exact',
+      path: HOST_TOKEN_ROUTE,
+      handler: guarded(gate, ['PUT', 'DELETE'], async (req, res) => {
+        const body = await readJsonBody(req, false)
+        const state = req.method?.toUpperCase() === 'DELETE' ? await service.clearHostToken(body) : await service.setHostToken(body)
+        sendJson(res, 200, { ok: true, state })
+      }),
+    }),
   ]
   return () => { for (const dispose of disposers) dispose() }
 }

package/src/skill-update/change.ts

@@ -0,0 +1,81 @@
+/**
+ * 检查 SKILL 修改：从 dsh-repo 镜像读取分析时的提交中 SKILL 目录的文件，与提议
+ * 的文件比较，算出逐文件行数和 unified diff，不改动任何镜像或快照。提议内容的
+ * 摘要用作新分支名，提交本身经 dsh-repo 完成。
+ *
+ * @module dsh-guanxiang/skill-update/change
+ */
+
+import { createHash } from 'node:crypto'
+import { createTwoFilesPatch, structuredPatch } from 'diff'
+import type { DshRepoService } from 'dsh-repo/contract'
+import type { ProposedFile } from './proposal.ts'
+
+/** Line counts of one changed file. */
+export interface FileStat {
+  /** Path relative to the repository root. */
+  readonly path: string
+  readonly added: number
+  readonly removed: number
+}
+
+/** A proposal compared with its base commit. */
+export interface PreparedChange {
+  readonly base: string
+  /** Hexadecimal digest of the base commit and the changed files; names the branch. */
+  readonly digest: string
+  readonly files: readonly FileStat[]
+  /** Unified diff from the base commit to the proposal, limited to the skill directory. */
+  readonly diff: string
+}
+
+/** Where a proposal applies. */
+export interface ChangeTarget {
+  readonly url: string
+  /** Commit the analysis ran on. */
+  readonly base: string
+  /** Skill directory relative to the repository root, `/`-separated. */
+  readonly skillDir: string
+}
+
+/**
+ * Compare the proposed files with the skill directory of the base commit.
+ * @param repos - the `dshRepos` service holding the mirror.
+ * @param target - repository, base commit, and skill directory.
+ * @param files - proposed files relative to the skill directory.
+ * @param signal - cancellation.
+ * @returns per-file line counts, the diff, and the digest; `files` is empty when nothing changes.
+ * @throws when a proposed path replaces a symbolic link, a submodule, or a directory, or the mirror cannot be read.
+ */
+export async function prepareChange(repos: DshRepoService, target: ChangeTarget, files: readonly ProposedFile[], signal?: AbortSignal): Promise<PreparedChange> {
+  const { url, base, skillDir } = target
+  const listing = await repos.listMirrorTree(url, base, skillDir, signal === undefined ? {} : { signal })
+  const types = new Map(listing.map(entry => [entry.path, entry.type]))
+  const stats: FileStat[] = []
+  const patches: string[] = []
+  const digest = createHash('sha256').update(`${base}\n`)
+  for (const file of [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+    const path = `${skillDir}/${file.path}`
+    const type = types.get(path)
+    if (type === 'symlink') throw new Error(`${path} 在仓库中是符号链接，不能用提议覆盖`)
+    if (type === 'dir' || type === 'submodule') throw new Error(`${path} 在仓库中是目录，不能用文件覆盖`)
+    const before = type === 'file' ? await repos.readMirrorFile(url, base, path, signal === undefined ? {} : { signal }) ?? '' : undefined
+    if (before === file.content) continue
+    const structured = structuredPatch(path, path, before ?? '', file.content, undefined, undefined, { context: 3 })
+    let added = 0
+    let removed = 0
+    for (const hunk of structured.hunks) {
+      for (const line of hunk.lines) {
+        if (line.startsWith('+')) added += 1
+        else if (line.startsWith('-')) removed += 1
+      }
+    }
+    stats.push({ path, added, removed })
+    const header = `diff --git a/${path} b/${path}\n${before === undefined ? 'new file mode 100644\n' : ''}`
+    const patch = createTwoFilesPatch(before === undefined ? '/dev/null' : `a/${path}`, `b/${path}`, before ?? '', file.content, undefined, undefined, { context: 3 })
+    // jsdiff starts with an `Index:`-style separator line that git diffs do not have.
+    patches.push(header + patch.replace(/^=+\n/, ''))
+    digest.update(`${path}\0${file.content}\0`)
+  }
+  return { base, digest: digest.digest('hex'), files: stats, diff: patches.join('') }
+}