@furongjun1999/dsh-memory 0.4.5 → 0.4.6

package/skills/skills/lingshu-pylang/units/pylang-f6ebb66e/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pylang-f6ebb66e
+description: >-
+  优先级计算 / 语法-优先级 / CPython 优 / 表达式优先级求值（2+3。用户提到这些词时使用本技能。
+  场景：对照：CPython 优先级（乘除高于加减，括号最高）。
+  【不适用】Not for 以下场景：op 非 {*, +, -, /} 时
+license: MIT
+compatibility: >-
+  op ∈ {*, +, -, /}
+allowed-tools: Read Write Bash
+metadata:
+  version: "1.0"
+  skill-author: 灵枢（AEIS）
+  last-reviewed: "2026-08-29"
+  kccs:
+    trigger_words: ["优先级计算", "语法-优先级", "CPython 优", "表达式优先级求值（2+3"]
+    when: "op ∈ {*, +, -, /}"
+    sub: ["① op 分支处理"]
+    execute: "按 op 分派；循环迭代；顺序调用"
+    not_applicable: ["op 非 {*, +, -, /} 时"]
+  calibration: "对照：CPython 优先级（乘除高于加减，括号最高）"
+---
+
+# 语法-优先级（pylang-f6ebb66e）
+
+## When to use
+
+任务「优先级计算」；对照：CPython 优先级（乘除高于加减，括号最高）。
+
+## 克制条款（不适用条件）
+
+op 非 {*, +, -, /} 时
+
+## How to execute
+
+按 op 分派；循环迭代；顺序调用
+
+## Verification
+
+- 单元样例 4 条（cases 断言）
+- 物理基底：按 calibration 对照（编译/运行/断言裁决）
+
+## References
+
+- 单元库：python_code_units.py「语法-优先级」

package/skills/skills/lingshu-pylang/units/pylang-f78bdcd7/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pylang-f78bdcd7
+description: >-
+  函数机制 / 函数-定义调用 / mini_python. / 函数对象 / 调用。用户提到这些词时使用本技能。
+  场景：对照：mini_python.py 函数对象（参数+body+定义环境）与 call 调用（局部环境+参数绑定）。
+  【不适用】Not for 以下场景：条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+license: MIT
+compatibility: >-
+  参数 params/body/def_env 合法
+allowed-tools: Read Write Bash
+metadata:
+  version: "1.0"
+  skill-author: 灵枢（AEIS）
+  last-reviewed: "2026-08-29"
+  kccs:
+    trigger_words: ["函数机制", "函数-定义调用", "mini_python.", "函数对象", "调用"]
+    when: "参数 params/body/def_env 合法"
+    sub: []
+    execute: "函数对象：参数 + body + 定义环境（闭包基础）；调用：局部环境（父=定义环境）+ 参数绑定 + 执行 body（return 值）"
+    not_applicable: ["条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）"]
+  calibration: "对照：mini_python.py 函数对象（参数+body+定义环境）与 call 调用（局部环境+参数绑定）"
+---
+
+# 函数-定义调用（pylang-f78bdcd7）
+
+## When to use
+
+任务「函数机制」；对照：mini_python.py 函数对象（参数+body+定义环境）与 call 调用（局部环境+参数绑定）。
+
+## 克制条款（不适用条件）
+
+条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+
+## How to execute
+
+函数对象：参数 + body + 定义环境（闭包基础）；调用：局部环境（父=定义环境）+ 参数绑定 + 执行 body（return 值）
+
+## Verification
+
+- 单元样例 1 条（cases 断言）
+- 物理基底：按 calibration 对照（编译/运行/断言裁决）
+
+## References
+
+- 单元库：python_code_units.py「函数-定义调用」

package/skills/skills/lingshu-pylang/units/pylang-f92bc49b/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pylang-f92bc49b
+description: >-
+  集合推导 / 推导式-集合推导 / CPython 集 / {x for x in 。用户提到这些词时使用本技能。
+  场景：对照：CPython 集合推导（{x for ...} 去重 + 条件过滤，与列表/字典推导同族）。
+  【不适用】Not for 以下场景：条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+license: MIT
+compatibility: >-
+  items 可迭代；cond 为谓词函数或 None（不过滤）
+allowed-tools: Read Write Bash
+metadata:
+  version: "1.0"
+  skill-author: 灵枢（AEIS）
+  last-reviewed: "2026-08-29"
+  kccs:
+    trigger_words: ["集合推导", "推导式-集合推导", "CPython 集", "{x for x in "]
+    when: "items 可迭代；cond 为谓词函数或 None（不过滤）"
+    sub: ["① 无谓词直接去重建集 ② 有谓词过滤后建集"]
+    execute: "set(items) 或 {x for x in items if cond(x)}"
+    not_applicable: ["条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）"]
+  calibration: "对照：CPython 集合推导（{x for ...} 去重 + 条件过滤，与列表/字典推导同族）"
+---
+
+# 推导式-集合推导（pylang-f92bc49b）
+
+## When to use
+
+任务「集合推导」；对照：CPython 集合推导（{x for ...} 去重 + 条件过滤，与列表/字典推导同族）。
+
+## 克制条款（不适用条件）
+
+条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+
+## How to execute
+
+set(items) 或 {x for x in items if cond(x)}
+
+## Verification
+
+- 单元样例 4 条（cases 断言）
+- 物理基底：按 calibration 对照（编译/运行/断言裁决）
+
+## References
+
+- 单元库：python_code_units.py「推导式-集合推导」

package/skills/skills/lingshu-pylang/units/pylang-fd7595f0/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pylang-fd7595f0
+description: >-
+  成对迭代 / 工具-成对迭代 / 相邻元素对。用户提到这些词时使用本技能。
+  场景：对照：itertools.pairwise——相邻元素对。
+  【不适用】Not for 以下场景：条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+license: MIT
+compatibility: >-
+  参数 seq 合法
+allowed-tools: Read Write Bash
+metadata:
+  version: "1.0"
+  skill-author: 灵枢（AEIS）
+  last-reviewed: "2026-08-29"
+  kccs:
+    trigger_words: ["成对迭代", "工具-成对迭代", "相邻元素对"]
+    when: "参数 seq 合法"
+    sub: ["① 调用 range；② 调用 len"]
+    execute: "顺序调用"
+    not_applicable: ["条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）"]
+  calibration: "对照：itertools.pairwise——相邻元素对"
+---
+
+# 工具-成对迭代（pylang-fd7595f0）
+
+## When to use
+
+任务「成对迭代」；对照：itertools.pairwise——相邻元素对。
+
+## 克制条款（不适用条件）
+
+条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+
+## How to execute
+
+顺序调用
+
+## Verification
+
+- 单元样例 3 条（cases 断言）
+- 物理基底：按 calibration 对照（编译/运行/断言裁决）
+
+## References
+
+- 单元库：python_code_units.py「工具-成对迭代」

package/skills/skills/lingshu-pylang/units/pylang-fda87aa1/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pylang-fda87aa1
+description: >-
+  字典反转 / 工具-字典反转 / 键值反转——值映射到键列 / 键值互换（值变键。用户提到这些词时使用本技能。
+  场景：对照：键值反转——值映射到键列表（invert）。
+  【不适用】Not for 以下场景：条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+license: MIT
+compatibility: >-
+  参数 d 合法
+allowed-tools: Read Write Bash
+metadata:
+  version: "1.0"
+  skill-author: 灵枢（AEIS）
+  last-reviewed: "2026-08-29"
+  kccs:
+    trigger_words: ["字典反转", "工具-字典反转", "键值反转——值映射到键列", "键值互换（值变键"]
+    when: "参数 d 合法"
+    sub: []
+    execute: "循环迭代"
+    not_applicable: ["条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）"]
+  calibration: "对照：键值反转——值映射到键列表（invert）"
+---
+
+# 工具-字典反转（pylang-fda87aa1）
+
+## When to use
+
+任务「字典反转」；对照：键值反转——值映射到键列表（invert）。
+
+## 克制条款（不适用条件）
+
+条件不满足即不适用（负路由：输入不满足生效条件时返回 None/不执行）
+
+## How to execute
+
+循环迭代
+
+## Verification
+
+- 单元样例 3 条（cases 断言）
+- 物理基底：按 calibration 对照（编译/运行/断言裁决）
+
+## References
+
+- 单元库：python_code_units.py「工具-字典反转」

package/src/index.ts

@@ -53,6 +53,8 @@ import { installMemoryHooks, type MemoryHooksOptions } from './hooks.js'
 import { installRoleplayWeb } from './lib/roleplay_web.js'
 import { MdcgClient } from './lib/mdcg_client.js'
 import { describeDataPaths, mdcgRoot } from './lib/datapath.js'
+// 写入凭据密钥环（首启引导）：显式配置 → ~/.mdcg/token → 首启自动签发。
+import { resolveToken, type TokenResolution } from './lib/token_store.js'
 
 /**
  * 调试探针：记录 apply 失败到独立文件（绕过 DSH 日志系统）。
@@ -163,9 +165,10 @@ export const Config: z<Config> = z.object({
   maxRetryDelayMs: z.number().default(30_000),
   failOnStartupError: z.boolean().default(false),
   /** 角色扮演入口按钮（issue #8）：注入 dsh 首页右上角浮动入口；
-   * 关闭后不注入（/roleplay 页面仍可直接访问）。按钮本身支持拖动，
+   * **默认关闭**：该功能尚未开放，右上角浮动按钮会遮挡 GUI 侧边栏；
+   * 显式设 true 才注入；/roleplay 页面仍可直接访问。按钮支持拖动，
    * 位置记忆在浏览器 localStorage。 */
-  roleplayEntryButton: z.boolean().default(true),
+  roleplayEntryButton: z.boolean().default(false),
   /** 互维维护（v1.1）：心跳 10min / 任务验证双通道。 */
   mutual: z
     .object({
@@ -218,9 +221,28 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   // 提供完整认知面。插件侧唯一显式入口：src/lib/mdcg_client.ts（一方法 = 一条 MCP 调用）。
   let mdcg: MdcgClient | null = null
   let brainReady = false
+  /** 写入凭据解析结果（首启引导；诊断与启动日志用）。 */
+  let cred: TokenResolution | null = null
   /** 记忆真源解析结果（「新写入去哪」）——用户可改：env > paths.json > 配置 > 默认自身仓 data/。 */
   const resolvedRoot = mdcgRoot(config.mdcg.root)
   if (config.mdcg.enabled) {
+    // ── 写入凭据解析（首启引导）：显式配置 → 密钥环 → 首启自动签发 ──
+    // 为什么需要：md_cg 无令牌即降级只读 guest，自动记忆 / 转录 / 角色落图
+    // **静默不落盘**——「装好了插件，但记忆永远是空的」是最难定位的失效形态。
+    // 解析顺序与「自动签发不降低实际安全强度」的论证见 lib/token_store.ts 文件头。
+    // legacy env 认证本就等价于「已显式授权」→ 不再签发，避免多签一枚无用令牌。
+    const legacyAuth = config.env.MDCG_LEGACY_ENV_AUTH ?? process.env.MDCG_LEGACY_ENV_AUTH
+    const resolution = resolveToken({
+      python: config.python,
+      configured: config.env.MDCG_TOKEN,
+      actor: config.mdcg.actor,
+      clearance: config.mdcg.clearance,
+      autoIssue: !legacyAuth,
+    })
+    cred = resolution
+    // 注入子进程 env：显式配置与密钥环都在此汇合成**唯一**的 MDCG_TOKEN。
+    const mdcgEnv: Record<string, string> = { ...config.env }
+    if (resolution.token) mdcgEnv.MDCG_TOKEN = resolution.token
     mdcg = new MdcgClient({
       python: config.python,
       args: config.moduleArgs,
@@ -229,7 +251,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
       tenant: config.mdcg.tenant,
       clearance: config.mdcg.clearance,
       identity: config.identity,
-      env: config.env,
+      env: mdcgEnv,
       timeoutMs: config.toolCallTimeoutMs,
       maxRetryDelayMs: config.maxRetryDelayMs,
     })
@@ -251,18 +273,25 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
         + '核验按白箱纪律 fail-closed；桥将后台重连并在就绪后补注册工具。',
       )
     }
-    // 写入凭据检查（fail-closed，且**默认关闭**）：md_cg 身份优先级
-    // ① MDCG_TOKEN ② MDCG_LEGACY_ENV_AUTH=1 ③ 都没有 → 只读 guest。
-    // 默认即第 ③ 种：读 / 召回 / 时间线照常，但自动记忆、转录、角色落图**不落盘**。
-    // 是否打开写权限由用户自行决定（见 cordis.yml.example 的「写入凭据」段），
-    // 插件不代为注入任何凭据，只在启动时告警——避免「看起来在记忆、其实没落盘」。
+    // 写入凭据检查（fail-closed）：凭据来源已由 token_store 解析（见上）。
+    // ① 显式配置 / 密钥环 / 首启自动签发 → 可写；② 都不行 → 只读 guest，必须告警。
+    // 告警仍是硬要求：guest 下读 / 召回 / 时间线照常，但自动记忆、转录、
+    // 角色落图**不落盘**——不吭声就是「看起来在记忆、其实没落盘」。
     const authEnv: Record<string, string | undefined> = { ...process.env, ...config.env }
-    if (!authEnv.MDCG_TOKEN && !authEnv.MDCG_LEGACY_ENV_AUTH) {
+    if (!cred.token && !authEnv.MDCG_LEGACY_ENV_AUTH) {
       ctx.logger.warn(
-        'dsh-memory: 未配置认知图写入凭据（默认关闭），以只读 guest 运行——'
+        'dsh-memory: 认知图写入凭据不可用，以只读 guest 运行——'
         + '读 / 召回 / 时间线可用，但自动记忆、转录、角色落图不会落盘。'
-        + '要打开：签发令牌 MDCG_TOKEN（推荐）或设 MDCG_LEGACY_ENV_AUTH=1，'
-        + '经 config.env 注入，见 cordis.yml.example。')
+        + (cred.note ? `原因：${cred.note}。` : '')
+        + '要打开：签发令牌 MDCG_TOKEN 经 config.env 注入（见 cordis.yml.example），'
+        + '或删除密钥环后重启以重新自动签发。')
+    } else if (cred.source === 'issued') {
+      // 首启引导：自动签发是**改变用户可写权限**的动作，必须留痕（含关闭/吊销方式）。
+      ctx.logger.info(`dsh-memory: ${cred.note}`)
+    } else {
+      ctx.logger.info(
+        `dsh-memory: 认知图写入凭据来源=${cred.source}（密钥环 ${cred.keyringPath}）`
+        + '——自动记忆 / 转录 / 角色落图已开启')
     }
   } else {
     ctx.logger.warn('dsh-memory: mdcg.enabled=false —— 大脑（认知图）未启动，工具与自动记忆不可用')

package/src/lib/mdcg_client.ts

@@ -74,6 +74,26 @@ const DEFAULT_ARGS = ['-m', 'md_cg.mcp_server']
  *  compiler | test | measurement | formal_proof | data | other（other 不算强依据）。 */
 const STRONG_BASIS = new Set(['compiler', 'test', 'measurement', 'formal_proof', 'data'])
 
+/**
+ * 请求级**单元身份**（MCP 参数 `as_unit`）。
+ *
+ * 与 `md_cg/tokens.py` 的 `POSITION_ROLES` 同源（record/reflect/verify/
+ * output/sustain）；大脑侧 `narrowed_principal` 对未知值 fail-closed 报错。
+ *
+ * 语义（关键）：`as_unit` 只能**收窄**权限、不能放大——大脑侧以「与 owner 求交 +
+ * 管理权恒 False」保证，故填错的最坏结果等于不填（owner 全权），**不可能提权**。
+ *
+ * 本客户端**只在写入 / 裁决路径注入**，且只注入与落层确定匹配的单元：
+ *   · 记忆沉淀 / 转录 / 角色定义 → `record`（落 contextual / knowledge，在 record
+ *     的 layers_allow 内）；
+ *   · 外部裁决回填               → `verify`（cg op=verify）。
+ * **只读调用一律不注入**：record / output 的 `clearance_cap=internal`，注入会把
+ * owner 的 private 读能力一并压低（读不到私有记忆＝功能退化），而读无副作用，
+ * 收窄无收益。`write()` 同样不注入——它被用于写 self / structural 层（角色锚点
+ * 需 designer 权限），注入 `record` 会直接打断角色落图。
+ */
+export type LingshuUnit = 'record' | 'reflect' | 'verify' | 'output' | 'sustain'
+
 function collectItems(payload: unknown): Array<Record<string, unknown>> {
   if (Array.isArray(payload)) return payload as Array<Record<string, unknown>>
   if (payload && typeof payload === 'object') {
@@ -143,18 +163,23 @@ export class MdcgClient {
     this.bridge.dispose()
   }
 
-  /** 原始 cg 调用（逃生口；显式传参，不做推断）。 */
-  async cg(args: Record<string, unknown>): Promise<unknown> {
-    return this.call('cg', args)
+  /** 原始 cg 调用（逃生口；显式传参，不做推断）。
+   *  `asUnit` = 本次调用的请求级单元身份（见 LingshuUnit）；只收窄、不提权。 */
+  async cg(args: Record<string, unknown>, asUnit?: LingshuUnit): Promise<unknown> {
+    return this.call('cg', args, asUnit)
   }
 
   /** 原始 stg 调用（时间线/关系/锚点/一致性）。 */
-  async stg(args: Record<string, unknown>): Promise<unknown> {
-    return this.call('stg', args)
+  async stg(args: Record<string, unknown>, asUnit?: LingshuUnit): Promise<unknown> {
+    return this.call('stg', args, asUnit)
   }
 
-  private async call(tool: string, args: Record<string, unknown>): Promise<unknown> {
-    const result: McpCallResult = await this.bridge.callTool(tool, args)
+  private async call(tool: string, args: Record<string, unknown>,
+                     asUnit?: LingshuUnit): Promise<unknown> {
+    // as_unit 由大脑侧 mcp_server.call_tool 在同一进程内消费并收窄 principal，
+    // 不从 args 向下透传，故不会污染各 tool handler 的参数解析。
+    const payload = asUnit ? { ...args, as_unit: asUnit } : args
+    const result: McpCallResult = await this.bridge.callTool(tool, payload)
     const text = (result.content ?? [])
       .filter((c) => c.type === 'text')
       .map((c) => c.text ?? '')
@@ -189,8 +214,9 @@ export class MdcgClient {
    * ⚠️ 唯一写入通道：**不可**改用 `cg(op=write)`（那条路径会被 audit 拦住，
    * 见文件头「写入为什么不能走 cg(op=write)」）。gated=false 直写 `MdCG.add`
    * （默认 layer=knowledge），gated=true 走主动遗忘闸门。 */
-  private writeNode(args: Record<string, unknown>): Promise<unknown> {
-    return this.call('mdcg_remember', args)
+  private writeNode(args: Record<string, unknown>,
+                    asUnit?: LingshuUnit): Promise<unknown> {
+    return this.call('mdcg_remember', args, asUnit)
   }
 
   /** 写入：新增/覆盖一个记忆节点（直写 `MdCG.add`，不经审核队列）。 */
@@ -209,7 +235,8 @@ export class MdcgClient {
    * role 取 user | assistant | tool-output（见 md_cg/sources.py 的
    * SESSION_LAYER / DSHSessionSource 事件映射）。 */
   remember(content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
-    return this.writeNode({ content, gated: true, layer: 'contextual', ...extra })
+    // 落层 contextual 固定在 record 白名单内 → 声明 record 单元（不得写 self/anchor）。
+    return this.writeNode({ content, gated: true, layer: 'contextual', ...extra }, 'record')
   }
 
   /** 语义召回（AEIS `recall` 的对应物）：`cg(op=read, query)` → md_cg 检索。
@@ -220,7 +247,8 @@ export class MdcgClient {
 
   /** 外部裁决回填：为已有节点写 confirmed/weakened/falsified。 */
   verify(nodeId: string, evidence: string, verdict: string): Promise<unknown> {
-    return this.cg({ op: 'verify', node_id: nodeId, evidence, verdict })
+    // 裁决回填声明 verify 单元：只写 rejected/contextual，不得改被验证内容。
+    return this.cg({ op: 'verify', node_id: nodeId, evidence, verdict }, 'verify')
   }
 
   /** 最近记忆。 */
@@ -305,25 +333,30 @@ export class MdcgClient {
 
   /** 角色定义落图：layer=knowledge，tags=['roleplay','role:<id>']。 */
   writeRole(roleId: string, content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
-    return this.write(content, {
+    // 落层固定 knowledge（在 record 白名单内）→ 声明 record 单元。
+    // ⚠️ 不经 this.write()：那是不注入单元的通用直写口（还要写 self 层锚点）。
+    return this.writeNode({
+      content,
       node_id: `roleplay_role_${roleId}`,
       layer: 'knowledge',
       tags: ['roleplay', `role:${roleId}`, 'roleplay:role'],
       importance: 0.7,
       ...extra,
-    })
+    }, 'record')
   }
 
   /** 角色对话转录落图：layer=contextual，tags=['roleplay','role:<id>','session:<cid>']。 */
   writeTranscript(roleId: string, sessionId: string, who: 'user' | 'assistant',
                   content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
     const stamp = Date.now()
-    return this.write(content, {
+    // 落层固定 contextual（在 record 白名单内）→ 声明 record 单元。
+    return this.writeNode({
+      content,
       node_id: `roleplay_turn_${roleId}_${sessionId}_${stamp}`,
       layer: 'contextual',
       tags: ['roleplay', `role:${roleId}`, `session:${sessionId}`, `turn:${who}`],
       importance: 0.4,
       ...extra,
-    })
+    }, 'record')
   }
 }

package/src/lib/token_store.ts

@@ -0,0 +1,183 @@
+/**
+ * token_store.ts —— 灵枢写入凭据的**密钥环**（默认 `~/.mdcg/token`）
+ *
+ * 要解决的问题（首启静默失效）
+ * ------------------------------------------------
+ * 灵枢大脑（md_cg）用令牌做身份与权限判定：**无令牌即降级只读 guest**，
+ * 此时自动记忆 / 对话转录 / 角色落图**全部不落盘**（`_build_principal` 的
+ * guest 分支，且启动会告警）。对「不知道需要签发令牌」的用户，这表现为
+ * **「装好了插件，但记忆永远是空的」**——一种没有任何报错的失效形态。
+ *
+ * 本模块把这条路径补齐，解析顺序（高 → 低）：
+ *   ① `config.env.MDCG_TOKEN` —— 显式配置，原样尊重，**完全不介入**；
+ *   ② 进程 env `MDCG_TOKEN` —— 同上；
+ *   ③ 密钥环 `~/.mdcg/token`（0600）—— 已签发过则复用；
+ *   ④ 都没有 → **首启自动签发**一枚 designer 令牌并写入密钥环。
+ *
+ * 为什么密钥环可以自动签发（安全论证）
+ * ------------------------------------------------
+ * 能读到该文件的进程，本就以该用户身份运行，也就本就能读写该用户的全部文件
+ * ——自动签发**不降低实际安全强度**。真正需要显式管理令牌的场景（多用户机 /
+ * 想要权职分离 / 审计要求）用 `MDCG_AUTO_ISSUE=0` 关闭，改走手工签发。
+ *
+ * 与 `md_cg/tokens.py` 的对应
+ * ------------------------------------------------
+ * 密钥环与 `tokens.py` 的 `~/.mdcg/_tokens.json`（令牌记录）同目录，但**职责不同**：
+ * 密钥环存**明文令牌**（给本机客户端用），`_tokens.json` 存**哈希与元数据**（校验用）。
+ * 二者格式不做任何修改——本模块只是 `python -m md_cg.tokens issue` 的一层封装。
+ */
+import { spawnSync } from 'node:child_process'
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** 凭据来源（用于启动日志与故障定位）。 */
+export type TokenSource =
+  | 'config'       // config.env.MDCG_TOKEN（显式配置，原样尊重）
+  | 'process-env'  // 插件进程 env 的 MDCG_TOKEN
+  | 'keyring'      // 密钥环 ~/.mdcg/token
+  | 'issued'       // 首启自动签发并写入密钥环
+  | 'disabled'     // 显式关闭自动签发，且无既有凭据
+  | 'none'         // 签发不可用（如 Python 不可执行），md_cg 侧将降级只读 guest
+
+export interface TokenResolution {
+  /** 明文令牌；未解析到时为 undefined（md_cg 侧降级只读 guest）。 */
+  token?: string
+  source: TokenSource
+  /** 人类可读的补充说明（写启动日志用，含关闭 / 吊销方式）。 */
+  note?: string
+  /** 密钥环路径（诊断用）。 */
+  keyringPath: string
+}
+
+export interface ResolveTokenOptions {
+  /** Python 可执行文件（与 md_cg 子进程同源，保证 import 环境一致）。 */
+  python: string
+  /** 显式配置的令牌（config.env.MDCG_TOKEN）。 */
+  configured?: string
+  /** 签发主体标识（写入令牌记录，默认 dsh-memory）。 */
+  actor?: string
+  /** 签发角色（默认 designer = 设计者载体；其它角色见 tokens.ROLE_SPECS）。 */
+  role?: string
+  /** 签发密级上限（默认 internal，与 md_cg 的 DEFAULT_SENSITIVITY 对齐）。 */
+  clearance?: string
+  /** 是否允许首启自动签发（默认 true；legacy env 认证场景应传 false）。 */
+  autoIssue?: boolean
+  /** 密钥环路径覆盖（默认 ~/.mdcg/token）。 */
+  keyringPath?: string
+}
+
+/** 默认密钥环路径：与 md_cg 的 `~/.mdcg/` 约定同目录（`_tokens.json` 亦在此）。 */
+export function defaultKeyringPath(): string {
+  return join(homedir(), '.mdcg', 'token')
+}
+
+/** 读取密钥环；不存在 / 不可读 / 空文件一律返回 undefined（不抛异常）。 */
+function readKeyring(path: string): string | undefined {
+  try {
+    const t = readFileSync(path, 'utf-8').trim()
+    return t || undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** 写入密钥环并尽力收紧权限。 */
+function writeKeyring(path: string, token: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, token + '\n', { encoding: 'utf-8', mode: 0o600 })
+  try {
+    // Windows 上 chmod 仅能置只读位（真实保护来自用户目录 ACL），
+    // 与 md_cg tokens._save 同策略：不可设则忽略，不因此中断签发。
+    chmodSync(path, 0o600)
+  } catch { /* 平台不支持则忽略 */ }
+}
+
+interface IssueOutcome {
+  token?: string
+  tokenId?: string
+  error?: string
+}
+
+/** 调 `python -m md_cg.tokens issue` 签一枚令牌（同步，仅首启一次）。 */
+function issueToken(python: string, role: string, actor: string, clearance: string): IssueOutcome {
+  let r
+  try {
+    r = spawnSync(
+      python,
+      ['-m', 'md_cg.tokens', 'issue',
+        '--role', role, '--actor', actor, '--clearance', clearance],
+      {
+        encoding: 'utf-8',
+        windowsHide: true,
+        timeout: 15_000,
+        // 与工作纪律第 15 条同源：显式 UTF-8 + PYTHONUTF8，规避 Windows GBK 解码异常
+        env: { ...process.env, PYTHONUTF8: '1', PYTHONIOENCODING: 'utf-8' },
+      },
+    )
+  } catch (e) {
+    return { error: `无法执行 ${python}：${e instanceof Error ? e.message : String(e)}` }
+  }
+  if (r.error) return { error: `无法执行 ${python}：${r.error.message}` }
+  if (r.status !== 0) {
+    const detail = (r.stderr || r.stdout || '').trim().replace(/\s+/g, ' ').slice(0, 200)
+    return { error: `md_cg.tokens issue 退出码 ${r.status}${detail ? `：${detail}` : ''}` }
+  }
+  try {
+    const out = JSON.parse(r.stdout || '{}') as { token?: string; token_id?: string }
+    if (!out.token) return { error: '签发输出缺少 token 字段' }
+    return { token: out.token, tokenId: out.token_id }
+  } catch (e) {
+    return { error: `签发输出不是合法 JSON：${e instanceof Error ? e.message : String(e)}` }
+  }
+}
+
+/** `MDCG_AUTO_ISSUE` 是否显式关闭（0/false/no/off，忽略大小写）。 */
+function autoIssueDisabledByEnv(): boolean {
+  const v = (process.env.MDCG_AUTO_ISSUE ?? '').trim().toLowerCase()
+  return v === '0' || v === 'false' || v === 'no' || v === 'off'
+}
+
+/**
+ * 解析写入凭据：显式配置 → 进程 env → 密钥环 → 首启自动签发。
+ *
+ * 纯函数式（无模块级缓存）：一次插件激活只调用一次，且返回值须与当下磁盘
+ * 状态一致，缓存反而会让「用户刚删了密钥环」的修复动作不生效。
+ */
+export function resolveToken(opts: ResolveTokenOptions): TokenResolution {
+  const keyringPath = opts.keyringPath ?? defaultKeyringPath()
+
+  const configured = (opts.configured ?? '').trim()
+  if (configured) return { token: configured, source: 'config', keyringPath }
+
+  const fromEnv = (process.env.MDCG_TOKEN ?? '').trim()
+  if (fromEnv) return { token: fromEnv, source: 'process-env', keyringPath }
+
+  const fromRing = readKeyring(keyringPath)
+  if (fromRing) return { token: fromRing, source: 'keyring', keyringPath }
+
+  if (opts.autoIssue === false) {
+    return { source: 'disabled', keyringPath, note: '本场景未启用自动签发（autoIssue=false）' }
+  }
+  if (autoIssueDisabledByEnv()) {
+    return { source: 'disabled', keyringPath, note: 'MDCG_AUTO_ISSUE 已关闭自动签发' }
+  }
+
+  const role = opts.role ?? 'designer'
+  const actor = opts.actor ?? 'dsh-memory'
+  const clearance = opts.clearance ?? 'internal'
+  const r = issueToken(opts.python, role, actor, clearance)
+  if (!r.token) {
+    return { source: 'none', keyringPath, note: r.error }
+  }
+  writeKeyring(keyringPath, r.token)
+  return {
+    token: r.token,
+    source: 'issued',
+    keyringPath,
+    note: `已自动签发认知图写入凭据（role=${role}, actor=${actor}, `
+      + `clearance=${clearance}, token_id=${r.tokenId}），明文存于 ${keyringPath}。`
+      + '关闭自动签发：设 MDCG_AUTO_ISSUE=0；'
+      + `吊销：python -m md_cg.tokens revoke --token-id ${r.tokenId}。`,
+  }
+}