dsh-caduceus 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArtomYuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# dsh-caduceus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 **DeepSeek Harness（dsh）** 接到 **飞书 / Lark** 的插件：一个话题一个会话，人格块自动同步，过程卡片承载状态与答案，并带 `/status`、`/doctor`、`/sessions` 等命令。
+
+## 安装
+
+### 路径 1：一次性命令行（推荐）
+
+发布到 npm 后，装包时直接放行依赖构建脚本：
+
+```bash
+dsh plugin --profile web add dsh-caduceus --allow-build=protobufjs
+```
+
+### 路径 2：先授权再装（不带 flag 也能装）
+
+在目标 profile 目录的 `pnpm-workspace.yaml` 里加：
+
+```yaml
+onlyBuiltDependencies:
+  - protobufjs
+```
+
+然后正常安装即可：
+
+```bash
+dsh plugin --profile web add dsh-caduceus
+```
+
+### 路径 3：本地 tgz
+
+```bash
+npm pack
+dsh plugin --profile web add ./dsh-caduceus-0.1.0.tgz --allow-build=protobufjs
+```
+
+### 安装坑（实测 pnpm 11.7.0）
+
+- **flag 必须用等号**：`--allow-build=protobufjs` 可以；`--allow-build protobufjs`（空格）会报
+  `ERR_PNPM_ALLOW_BUILD_MISSING_PACKAGE` 并安装失败。
+- **为什么需要放行**：`protobufjs` 是飞书 SDK 的传递依赖；pnpm ≥10 默认不执行依赖包的安装/构建脚本，
+  未放行时安装会以 `ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: protobufjs@7.6.6` 失败。
+- **确认装上了**：安装后执行
+
+  ```bash
+  dsh --profile web --dump-config | grep dsh-caduceus
+  ```
+
+  应至少输出 2 行（两条 caduceus entry）。
+
+安装/启用后由宿主统一重启 dsh；本包不控制服务。
+
+## 配置
+
+在 profile 的 bundle 配置里提供：
+
+| 配置 | 默认 | 说明 |
+|:--|:--|:--|
+| `appId` / `appSecret` | — | 飞书应用凭证；也可用 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` |
+| `defaultCwd` | 当前进程 cwd | 新建会话的工作目录 |
+| `groupSessionsPerUser` | `true` | 普通群按发送者隔离会话；话题不受影响 |
+| `busyMode` | `queue` | 群里忙时的投递：`queue` / `steer` / `interrupt` |
+| `cardThrottleMs` | `400` | 过程卡 patch 节流（毫秒） |
+| `personaAutoSync` | `true` | 启动时把 SOUL 同步到 `$DSH_HOME/AGENTS.md` |
+| `agentPreset` | `standard` | 新会话挂载的 dsh agent preset |
+| `logLevel` | `info` | 文件日志级别：`info` / `debug` |
+
+人格：SOUL 源按 `$DSH_HOME/SOUL.md` → `$DSH_AGENTS_HOME/SOUL.md` 查找，投影到 `$DSH_HOME/AGENTS.md` 的标记块；命令见下。
+
+## 命令
+
+| 命令 | 说明 |
+|:--|:--|
+| `/new` | 立即创建新会话（旧会话保留） |
+| `/sessions [--all]` | 列出当前会话或同聊天全部会话（含历史） |
+| `/rename <标题>` | 重命名当前会话 |
+| `/resume [id\|尾号]` | 恢复上一条或按完整 id / ≥8 位尾号切换 |
+| `/adopt <id\|尾号>` | 把无归属的历史会话收养到当前 scope |
+| `/selfcheck` | 立即重跑自检并输出逐项明细 |
+| `/doctor [--json]` | 体检报告：运行时 / 飞书 / 人格 / 会话 / 存储 / 版本 |
+| `/stop` | 中断正在运行的一轮 |
+| `/status` | 当前会话状态与自检摘要 |
+| `/persona [show\|sync]` | 查看或同步 SOUL 人格块 |
+| `/help` | 命令表 |
+
+## 故障排查
+
+- 启动日志里没有 `feishu long connection started`：先发 `/doctor` 看飞书凭证/长连接状态，再查文件日志。
+- 先发 `/doctor`：逐项看到 preset、工具数、人格投影、飞书连接、存储等状态；`/doctor --json` 可给脚本或他人排查。
+- 文件日志：`$DSH_HOME/caduceus/caduceus.log`（自动轮转，默认保留 3 份）。
+- 自检异常会同时在对话里发一条 `⚠ 自检异常 …（详情 /doctor）`；恢复后会发 `✓ 自检已恢复`。
+- 常见项：`preset:applied` 失败 = agent 没挂 preset（无工具/无人格）；`persona:fresh` 失败 = SOUL 与 `AGENTS.md` 不一致，发 `/persona sync` 或重启等自动同步。
+
+## 许可
+
+MIT。见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-caduceus bundle patch (design doc §7).
+#
+# One package, two self-owned entries. `dsh plugin add` is the only install step.
+#
+# NOTE (2026-10-31, verified on 0.2.1-rc.2): the base profile ALREADY mounts
+# `session-title` plus `session-title-llm` (first-prompt provider). Inserting a
+# second provider row here registers the same provider id twice and fails at
+# load, so this bundle adds no title row — the surface only calls
+# `sessionTitle.rename()` / `.get()`.
+- insert:
+    - id: caduceus-gateway
+      name: 'dsh-caduceus'
+    - id: caduceus-persona
+      name: 'dsh-caduceus/persona'

package/dist/atomic-write.d.ts

@@ -0,0 +1,6 @@
+/** The sibling temporary path used before the rename. */
+export declare function temporaryPathFor(filePath: string): string;
+/** Synchronous flavour (session store: small, called from sync code paths). */
+export declare function writeFileAtomicSync(filePath: string, data: string): void;
+/** Asynchronous flavour (persona sync: called from async command handlers). */
+export declare function writeFileAtomic(filePath: string, data: string): Promise<void>;

package/dist/atomic-write.js

@@ -0,0 +1,43 @@
+/**
+ * Small atomic-write helper shared by the session map and the persona block.
+ *
+ * Both files must survive a crash between "open" and "close": write the whole
+ * payload to a sibling temporary file, then rename it over the target. Rename
+ * is atomic on POSIX, so readers see either the old or the new file, never a
+ * torn one.
+ *
+ * @module dsh-caduceus/atomic-write
+ */
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** The sibling temporary path used before the rename. */
+export function temporaryPathFor(filePath) {
+    return `${filePath}.tmp`;
+}
+/** Synchronous flavour (session store: small, called from sync code paths). */
+export function writeFileAtomicSync(filePath, data) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tempPath = temporaryPathFor(filePath);
+    try {
+        writeFileSync(tempPath, data, { encoding: 'utf8', mode: 0o600 });
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+/** Asynchronous flavour (persona sync: called from async command handlers). */
+export async function writeFileAtomic(filePath, data) {
+    await mkdir(dirname(filePath), { recursive: true });
+    const tempPath = temporaryPathFor(filePath);
+    try {
+        await writeFile(tempPath, data, { encoding: 'utf8', mode: 0o600 });
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+}

package/dist/backfill.d.ts

@@ -0,0 +1,27 @@
+import { type HomeEnv } from './home.js';
+import type { LoggerLike } from './logger.js';
+import { type OwnershipOptions } from './ownership.js';
+import type { SessionStore } from './session-key.js';
+export interface SessionDirEntry {
+    readonly sessionId: string;
+    readonly dir: string;
+}
+export interface BackfillOptions {
+    /** Sessions root; defaults to `<DSH_HOME>/sessions`. */
+    readonly root?: string;
+    readonly env?: HomeEnv;
+    readonly ownership?: OwnershipOptions;
+    readonly logger?: LoggerLike;
+}
+export interface BackfillResult {
+    readonly scanned: number;
+    readonly adopted: number;
+    readonly skipped: number;
+}
+/** Discover caduceus-minted session directories (`feishu-*`), sorted for determinism. */
+export declare function scanSessionDirs(options?: BackfillOptions): SessionDirEntry[];
+/**
+ * Adopt discovered sessions into their owning scope key's history.
+ * Idempotent: a second run adopts 0.
+ */
+export declare function backfillSessionOwnership(store: SessionStore, options?: BackfillOptions): BackfillResult;

package/dist/backfill.js

@@ -0,0 +1,71 @@
+/**
+ * Startup ownership backfill: match dsh session directories to the caduceus
+ * ownership sidecar (or an ownership-carrying plain JSONL header) and append
+ * the session id to that scope key's history, so old sessions stay reachable
+ * even after a restart / history loss.
+ *
+ * Read-only scan of `<DSH_HOME>/sessions/<bucket>/<sessionId>/`; never creates
+ * agents or sessions. Session-map writes are the only side effect.
+ *
+ * @module dsh-caduceus/backfill
+ */
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { dshHome } from './home.js';
+import { silentLogger } from './logger.js';
+import { readOwnership, readOwnershipFromSessionDir, } from './ownership.js';
+/** Discover caduceus-minted session directories (`feishu-*`), sorted for determinism. */
+export function scanSessionDirs(options = {}) {
+    const root = options.root ?? join(dshHome(options.env), 'sessions');
+    const found = [];
+    let buckets;
+    try {
+        buckets = readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return found;
+    }
+    for (const bucket of buckets) {
+        let entries;
+        try {
+            entries = readdirSync(join(root, bucket), { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith('feishu-'))
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const sessionId of entries) {
+            found.push({ sessionId, dir: join(root, bucket, sessionId) });
+        }
+    }
+    return found;
+}
+/**
+ * Adopt discovered sessions into their owning scope key's history.
+ * Idempotent: a second run adopts 0.
+ */
+export function backfillSessionOwnership(store, options = {}) {
+    const logger = options.logger ?? silentLogger();
+    const ownershipOptions = options.ownership ?? {};
+    let scanned = 0;
+    let adopted = 0;
+    let skipped = 0;
+    for (const entry of scanSessionDirs(options)) {
+        scanned += 1;
+        const meta = readOwnership(entry.sessionId, ownershipOptions) ??
+            readOwnershipFromSessionDir(entry.dir);
+        if (meta === undefined) {
+            skipped += 1;
+            continue;
+        }
+        if (store.appendHistory(meta.scopeKey, entry.sessionId))
+            adopted += 1;
+    }
+    logger.info(`backfill: scanned=${scanned} adopted=${adopted} skipped=${skipped}`);
+    return { scanned, adopted, skipped };
+}

package/dist/bridge/bridge.d.ts

@@ -0,0 +1,24 @@
+import { type StatusEventLike, type StatusSnapshot } from '../status.js';
+import type { FeishuCard, InboundMessage } from '../transport/types.js';
+import type { BridgeOptions } from './types.js';
+/** Extract the assistant's text from one `assistant/message` payload. */
+export declare function assistantTextFromEvent(data: unknown): string;
+/** Extract the raw `turn/end` reason kind. */
+export declare function turnEndReasonKind(data: unknown): string | undefined;
+/** Extract the accepted title from a `session/title` event payload. */
+export declare function titleFromEvent(data: unknown): string | undefined;
+/** The bridge. Construct one per gateway entry. */
+export declare class Bridge {
+    #private;
+    constructor(options: BridgeOptions);
+    /** True when a session id belongs to a scope this bridge renders. */
+    ownsSession(sessionId: string): boolean;
+    /** Process one inbound message (serialized per scope). */
+    handleInbound(message: InboundMessage): Promise<void>;
+    /** Feed one dsh session event into the render/status layer. */
+    handleSessionEvent(session: {
+        readonly id: string;
+    }, event: StatusEventLike): Promise<void>;
+}
+/** Build the process card for one snapshot (exported for render tests). */
+export declare function progressCardForSnapshot(snapshot: StatusSnapshot, sessionTitle: string | undefined, recentEvent: string, tail: string, now: number, presetMissing?: boolean): FeishuCard;