@yijiancaotang/cli 0.0.0-stage → 1.0.0

package/dist/doctor.js

@@ -0,0 +1,214 @@
+import { authStatus, credentialTarget } from "./auth.js";
+import { isAbsolute, normalize } from "node:path";
+import { asRecord, CliError, READ_NETWORK_NEXT_ACTION, networkFailure } from "./errors.js";
+import { PLATFORM_IDS } from "./local-types.js";
+const recovery = "请先在网页核对设备，并吊销未保存的设备，再决定是否重新授权；不要自动重试领取令牌。";
+import { completeSkillInventory, skillNames } from "./skill-assets.js";
+const localMessages = {
+    local_inspection_failed: ["无法完成本地安装检查。", "请检查本地安装目录与文件安全后重新运行只读检查，不要自动覆盖或修复。"],
+    local_permission_denied: ["没有权限完成本地安装检查。", "请由本人检查本地安装目录的访问权限，不要自动提权或修改权限。"],
+    platform_permission_denied: ["没有权限检查平台程序目录。", "请由本人检查程序目录的访问权限，不要自动提权或修改权限。"],
+    platform_path_unsafe: ["平台目录未通过安全检查。", "请使用用户目录内的绝对路径，并由本人检查符号链接和权限。"],
+    platform_detection_failed: ["无法完成平台程序检查。", "请检查本地程序目录后重新运行只读检查，不要启动客户端。"],
+    command_missing: ["一间草堂命令行尚未完整安装。", "请核对本地安装结果，再由本人决定是否运行 setup。"],
+    command_modified: ["已有命令行与当前候选不一致。", "请保留现有文件，由本人核对安装来源和差异，不要自动覆盖或删除。"],
+    command_not_on_path: ["当前找不到可直接使用的一间草堂命令。", "请先核对安装是否完整；有已核验的完整路径时使用它，不修改 shell 或 PATH 配置。"],
+    command_version_unknown: ["无法确认本地命令行版本。", "请核对本地安装版本，不要自动升级或执行未知程序。"],
+    no_platform_detected: ["尚未识别到支持的 AI 客户端程序。", "请由本人确认 Claude Code、Codex、OpenClaw，或 macOS 上 Kimi Code、Kimi 工作模式、WorkBuddy 的程序安装位置后重新检查。"],
+    skills_missing: ["已识别平台的技能包不完整。", "请按当前安装包的技能清单核对所选平台，再由本人决定是否运行 setup。"],
+    skills_modified: ["已识别平台的技能内容与本包不一致。", "请保留现有技能，由本人核对差异；不要自动覆盖或删除。"],
+    skills_unsafe: ["已识别平台的技能目录未通过安全检查。", "请由本人检查技能目录的属主、权限和符号链接，不要自动修复或提权。"],
+};
+const hasLocalCode = (code) => Object.hasOwn(localMessages, code);
+const localAliases = {
+    command_not_installed: "command_missing",
+    no_supported_platform: "no_platform_detected",
+    skill_missing: "skills_missing",
+    skill_modified: "skills_modified",
+    skill_unsafe: "skills_unsafe",
+};
+function canonicalLocalCode(value) {
+    if (typeof value !== "string")
+        return undefined;
+    if (hasLocalCode(value))
+        return value;
+    return Object.hasOwn(localAliases, value) ? localAliases[value] : undefined;
+}
+const issue = (code, message, next_action) => ({ code, message, next_action });
+const localIssue = (code) => issue(code, ...localMessages[code]);
+const authMessages = {
+    unauthorized: ["当前授权缺失或已失效。", "请由本人核对网页授权状态，需要接入时再运行 auth login；不要输出令牌。"],
+    invalid_token: ["环境中的授权令牌格式无效。", "请由本人检查或取消当前环境的令牌覆盖，不要输出令牌。"],
+    invalid_token_environment: ["通用令牌变量没有绑定目标环境。", "使用按环境区分的开发变量；不要把测试令牌传给生产环境。"],
+    credential_unsafe: ["本地凭证未通过安全检查。", "请由本人检查凭证目录、属主、权限和目标环境，不要输出凭证内容。"],
+    credential_symlink: ["本地凭证路径包含符号链接，已拒绝访问。", "请由本人改用不含符号链接的真实用户目录和凭证路径后重试；不要自动删除链接、迁移凭证或放宽权限，也不要输出凭证内容。"],
+    credential_busy: ["另一项凭证操作尚未完成。", "请先等待同环境命令结束，再由本人核查残留锁；不要自动删锁或重新授权。"],
+    credential_conflict: ["当前环境已有另一份凭证。", recovery],
+    credential_migration_incomplete: ["旧凭据尚未确认清理，迁移未完成。", "请由本人处理旧凭据限制；不要读取其内容、绕过保护或重新授权。"],
+    authorization_delivery_unknown: ["无法确认领取结果，令牌可能已经交付。", recovery],
+    credential_save_failed: ["设备令牌已交付，但未能安全保存。", recovery],
+    installation_permission_denied: ["没有权限完成本地凭据操作。", "请由本人核对目标目录的访问、清空或删除限制；不要提权、放宽权限或自动重新授权。"],
+    invalid_auth_response: ["无法确认授权响应。", recovery],
+    invalid_response: ["无法确认服务响应。", recovery],
+    authorization_consumed: ["令牌已交付过，不能补领。", recovery],
+    expired_token: ["确认码已过期，这次没有完成接入。", "需要接入时，请本人重新运行 setup 或 auth login，取得新确认码后批准。"],
+    access_denied: ["这次接入已取消，没有建立新连接。", "只有本人需要时才重新发起接入。"],
+    authorization_cancelled: ["授权操作已取消。", "请先在网页核对实际状态，再决定是否重新授权；不要自动重试。"],
+    cancelled: ["操作已取消，授权状态尚未确认。", "请先在网页核对实际状态，再决定是否重新授权；不要自动重试。"],
+    network_error: ["无法完成授权联网验证。", READ_NETWORK_NEXT_ACTION],
+    permission_denied: ["授权检查被权限规则拒绝。", "请在网页检查设备权限和账号能力，不要自动扩大授权范围。"],
+    rate_limited: ["授权检查受到频率限制。", "请稍后重新运行只读 doctor，不要自动重试签发授权。"],
+    server_error: ["授权服务暂时不可用。", "请稍后重新运行只读 doctor，不要据此重新签发设备授权。"],
+    authorization_check_failed: ["无法完成授权检查。", "请由本人检查本地凭证和接入环境，不要输出凭证内容或自动重新授权。"],
+    authorization_failed: ["上一次授权操作未能确认完成。", recovery],
+};
+function authFailure(error, fromSetup, responseStatus, attempted = false, targetDirectory) {
+    const failure = error instanceof CliError ? error : undefined;
+    const exitCode = failure && [2, 3, 4, 5, 6, 7, 130].includes(failure.exitCode) ? failure.exitCode : 2;
+    let code = fromSetup ? "authorization_failed" : "authorization_check_failed";
+    if (failure && Object.hasOwn(authMessages, failure.code))
+        code = failure.code;
+    else if (exitCode === 130)
+        code = "cancelled";
+    else if (exitCode === 4)
+        code = "permission_denied";
+    else if (exitCode === 5)
+        code = "rate_limited";
+    else if (exitCode === 7)
+        code = "server_error";
+    else if (exitCode === 6 && !fromSetup)
+        code = "network_error";
+    const configurationFailure = code === "invalid_token_environment" || code === "invalid_token";
+    // A returned response is transport evidence; exception details are not.
+    const http = responseStatus;
+    const reached = typeof http === "number" && Number.isInteger(http) && http >= 100 && http <= 599;
+    let status = "unknown", network = "not_checked";
+    if (!fromSetup) {
+        if (reached)
+            network = "reachable";
+        if (code === "network_error" && attempted && !reached)
+            network = "unreachable";
+        if (exitCode === 7 && reached && Number(http) >= 500)
+            network = "unavailable";
+        if (code === "unauthorized")
+            status = http === 401 ? "invalid" : "missing";
+    }
+    if (configurationFailure)
+        status = "invalid";
+    const [message, nextAction] = code === "network_error" && !fromSetup ? [networkFailure(error, true).message, READ_NETWORK_NEXT_ACTION] : authMessages[code];
+    // Credential symlinks fail during the pre-authorization read. A later save
+    // failure is wrapped as credential_save_failed and still needs recovery.
+    const needsDeliveryRecovery = fromSetup && !configurationFailure && !["authorization_cancelled", "cancelled", "credential_symlink", "credential_migration_incomplete", "expired_token", "access_denied"].includes(code);
+    const action = needsDeliveryRecovery ? recovery : nextAction;
+    const links = code === "credential_save_failed" && asRecord(failure?.details)?.reason === "multiple_links";
+    return { issue: issue(code, links ? "设备令牌已交付，但凭据文件的链接数不是 1，未能安全保存。" : message, code === "installation_permission_denied" && targetDirectory ? `${action}目标目录：${targetDirectory}。` : action), exitCode, auth: { status }, network: { status: network } };
+}
+export async function doctor(ctx) {
+    const issues = [];
+    const add = (value) => { if (!issues.some((existing) => existing.code === value.code))
+        issues.push(value); };
+    let localExit = 0;
+    const addLocal = (code) => {
+        add(localIssue(code));
+        localExit = code === "platform_permission_denied" || code === "local_permission_denied" ? 4 : localExit || 2;
+    };
+    let local;
+    try {
+        const inspected = await ctx.inspectLocal();
+        if (!asRecord(inspected))
+            addLocal("local_inspection_failed");
+        else
+            local = inspected;
+    }
+    catch (error) {
+        const permission = (error instanceof CliError && error.exitCode === 4) || ["EACCES", "EPERM"].includes(String(asRecord(error)?.code));
+        addLocal((error instanceof CliError ? canonicalLocalCode(error.code) : undefined) ?? (permission ? "local_permission_denied" : "local_inspection_failed"));
+    }
+    const executable = local?.command?.executable_path;
+    const safeExecutable = typeof executable === "string" && executable.length <= 4096 && isAbsolute(executable) && normalize(executable) === executable
+        && !/[\x00-\x1f\x7f]/.test(executable) && executable.endsWith("/.local/bin/caotang") && local?.command?.installed === true ? executable : undefined;
+    const command = { installed: local?.command?.installed === true, on_path: local?.command?.on_path === true, version: "", ...(safeExecutable ? { executable_path: safeExecutable } : {}) };
+    if (local) {
+        const version = local.command?.version;
+        if (typeof version === "string" && version.length <= 80 && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?$/.test(version))
+            command.version = version;
+        if (!command.installed)
+            addLocal("command_missing");
+        if (!command.on_path && !safeExecutable)
+            addLocal("command_not_on_path");
+        if (command.installed && !command.version)
+            addLocal("command_version_unknown");
+        if (!Array.isArray(local.issues))
+            addLocal("local_inspection_failed");
+        else
+            for (const value of local.issues) {
+                const code = canonicalLocalCode(asRecord(value)?.code) ?? "local_inspection_failed";
+                if (code !== "no_platform_detected" || !ctx.agent || ctx.agent.platform) {
+                    if (code !== "command_not_on_path" || !safeExecutable)
+                        addLocal(code);
+                }
+            }
+    }
+    const ids = PLATFORM_IDS;
+    if (local && (!Array.isArray(local.platforms) || local.platforms.some((platform) => !platform || !ids.includes(platform.id)) || new Set(local.platforms.map((platform) => platform?.id)).size !== local.platforms.length))
+        addLocal("local_inspection_failed");
+    const platforms = ids.map((id) => {
+        const platform = Array.isArray(local?.platforms) ? local.platforms.find((candidate) => candidate?.id === id) : undefined;
+        const detected = platform?.detected === true;
+        const skills = Array.isArray(platform?.skills) ? platform.skills : [];
+        let status = "not_checked";
+        if (detected) {
+            status = skills.some((skill) => !skill || !skillNames.includes(skill.name) || skill.status === "unsafe" || !["installed", "missing", "modified"].includes(skill.status)) ? "unsafe"
+                : skills.some((skill) => skill.status === "modified") ? "modified"
+                    : !completeSkillInventory(skills.map(skill => skill.name)) || skills.some((skill) => skill.status !== "installed") ? "missing" : "installed";
+            if (status !== "installed")
+                addLocal(status === "unsafe" ? "skills_unsafe" : status === "modified" ? "skills_modified" : "skills_missing");
+        }
+        // Report aggregate skill state, not unchecked names or filesystem paths from the inspector.
+        const installed = detected ? new Set(skills.filter((skill) => skill?.status === "installed" && skillNames.includes(skill.name)).map((skill) => skill.name)).size : 0;
+        return { id, detected, skills: { status, installed, expected: skillNames.length } };
+    });
+    if (local && !platforms.some((platform) => platform.detected) && (!ctx.agent || ctx.agent.platform))
+        addLocal("no_platform_detected");
+    let auth = { status: "unknown" }, network = { status: "not_checked" }, authExit = 0;
+    if (ctx.authFailure !== undefined) {
+        const failed = authFailure(ctx.authFailure, true, undefined, false, credentialTarget(ctx.auth, ctx.authFailure).target_directory);
+        add(failed.issue);
+        auth = failed.auth;
+        network = failed.network;
+        authExit = failed.exitCode;
+    }
+    else {
+        let attempted = false, responseStatus;
+        try {
+            const validation = {
+                ...ctx.auth,
+                api: {
+                    baseUrl: ctx.auth.api.baseUrl,
+                    async request(path, options) {
+                        attempted = true;
+                        const response = await ctx.auth.api.request(path, options);
+                        responseStatus = response.status;
+                        return response;
+                    },
+                    upload: (url, headers, bytes) => ctx.auth.api.upload(url, headers, bytes),
+                },
+            };
+            const checked = asRecord((await authStatus(validation)).body);
+            if (checked?.status !== "authenticated" || !["file", "environment"].includes(String(checked.source)) || !["manual", "device"].includes(String(checked.kind)) || !["read_only", "read_write"].includes(String(checked.scope)))
+                throw new CliError("invalid_auth_response", "无法确认授权响应。", recovery, 7);
+            auth = { status: "valid", source: checked.source, kind: checked.kind, scope: checked.scope };
+            if (typeof checked.user_id === "string" && typeof checked.token_id === "string")
+                ctx.onIdentity?.({ userId: checked.user_id, tokenId: checked.token_id, kind: auth.kind, scope: auth.scope });
+            network = { status: "reachable" };
+        }
+        catch (error) {
+            const failed = authFailure(error, false, responseStatus, attempted, credentialTarget(ctx.auth, error).target_directory);
+            add(failed.issue);
+            auth = failed.auth;
+            network = failed.network;
+            authExit = failed.exitCode;
+        }
+    }
+    return { result: { status: 200, body: { readiness_scope: "local_cli_and_skills", ...(ctx.agent ? { agent_name: ctx.agent.name, own_connection: auth.status === "valid", skill_platform: ctx.agent.platform ?? "generic" } : {}), end_to_end_verified: false, command, platforms, auth, network, issues, next_actions: [...new Set(issues.map((value) => value.next_action))], ready: issues.length === 0 && auth.status === "valid" } }, exitCode: authExit || localExit };
+}

package/dist/errors.js

@@ -0,0 +1,214 @@
+import { writeMissingSections } from "./write-permissions.js";
+import { KNOWLEDGE_GROWTH_STEPS, knowledgeGrowthMetadata } from "./generated/knowledge-growth.js";
+export class CliError extends Error {
+    code;
+    nextAction;
+    exitCode;
+    details;
+    constructor(code, message, nextAction, exitCode = 2, details = {}) {
+        super(message);
+        this.code = code;
+        this.nextAction = nextAction;
+        this.exitCode = exitCode;
+        this.details = details;
+        this.name = "CliError";
+    }
+    toJSON() { return { code: this.code, message: this.message, next_action: this.nextAction, ...this.details }; }
+}
+export const asRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+export function legalConsentRequiredError(httpStatus = 403) {
+    const message = "协议已更新，请本人在网页确认后继续使用。";
+    return new CliError("legal_consent_required", message, "同意后原连接会恢复；不要重新授权、安装、读取凭据或换入口绕过确认。退出和注销仍可使用。", 4, { http_status: httpStatus, user_message: message, requires_user_action: true });
+}
+export const validToken = (value) => typeof value === "string" && value.length >= 16 && value.length <= 8192 && !/[\s\x00-\x1f\x7f]/.test(value);
+export const READ_NETWORK_NEXT_ACTION = "请先检查当前执行环境的联网权限和网络；恢复后可重新运行只读命令，不要连续重试或重新授权。";
+export function networkFailure(error, read) {
+    const known = asRecord(asRecord(error)?.details)?.network_cause;
+    const code = asRecord(error)?.code ?? asRecord(asRecord(error)?.cause)?.code;
+    const cause = known === "local_permission_denied" || code === "EPERM" || code === "EACCES" ? "local_permission_denied"
+        : known === "timeout" || code === "ETIMEDOUT" ? "timeout" : "unknown";
+    const message = read && cause === "local_permission_denied" ? "当前执行环境没有联网权限，未读到草堂内容。"
+        : read ? "网络请求未完成，未读到草堂内容。" : "无法确认一间草堂的请求结果。";
+    return new CliError("network_error", message, read ? READ_NETWORK_NEXT_ACTION : "先在网页核对结果，保留原幂等键；不要自动重试或重新上传。", 6, { network_cause: cause });
+}
+export function directPublicWriteError(local = false) {
+    return new CliError(local ? "invalid_arguments" : "direct_public_write_forbidden", "Agent 不能直接公开，请发起申请，由用户在网页确认", "直接写入的 visibility 只接受 private 或省略；不要自动改值重发。知识卡或项目需公开时，按本人明确意图使用 request visibility 发起申请，等本人网页确认；进展没有独立公开申请入口。不要重新授权或重试来绕过限制。", local ? 2 : 4, local ? {} : { http_status: 403 });
+}
+const codesByStatus = {
+    400: ["invalid_request", "invalid_upload"],
+    401: ["unauthorized", "upload_unauthorized"],
+    403: ["forbidden", "token_scope_insufficient", "second_confirmation_required", "capability_disabled", "moderation_blocked", "access_denied", "authorization_unavailable"],
+    404: ["not_found", "write_target_not_found", "upload_not_found"],
+    409: ["idempotency_conflict", "storage_quota_exceeded", "upload_unverified", "upload_in_progress", "upload_conflict", "authorization_consumed", "device_limit_reached"],
+    410: ["expired_token"],
+    429: ["slow_down", "device_issue_rate_limited", "device_auth_rate_limited", "rate_limited"],
+    500: ["write_failed", "write_publication_failed"],
+    503: ["storage_unavailable", "upload_busy", "device_auth_unavailable"]
+};
+// Account switches actually used by CLI operations. Never interpolate a
+// provider-supplied capability, message, ID or title into user guidance.
+const switchMessages = {
+    read_knowledge: "“读取知识”开关未开启。", read_projects: "“读取项目”开关未开启。",
+    read_workbench: "“读取工作台”开关未开启。", read_drafts: "“读取草稿”开关未开启。", read_notifications: "“读取通知”开关未开启。",
+    write_knowledge: "“写入知识卡”开关未开启。", write_knowledge_stage: "“推进知识长势”开关未开启。",
+    write_knowledge_sources: "“管理知识来源”开关未开启。", write_project: "“写入项目”开关未开启。",
+    write_project_update: "“写入项目进展”开关未开启。", write_project_cognition: "“写入认知摘要”开关未开启。",
+    delete_or_archive: "“删除或归档申请”开关未开启；申请仍须本人在网页确认。",
+};
+export function unverifiedSwitchError() {
+    return new CliError("permission_denied", "当前操作权限不足，无法核实具体开关。", "请本人到网页的 Agent 管理核对账号与设备权限；不要重新授权或重试来绕过限制。", 4, { http_status: 403 });
+}
+export function singleSwitchMetadata(body) {
+    return !Object.hasOwn(body, "missing_sections") || Array.isArray(body.missing_sections) && body.missing_sections.length === 0;
+}
+// Only the stage PATCH may interpret these receipts. Do not reflect IDs or server text.
+export function checkApplicationReceipt(result, requestedStage) {
+    const body = asRecord(result.body);
+    if (!body)
+        return;
+    const code = body.code ?? body.error;
+    if ((body.code !== undefined && body.code !== code) || (body.error !== undefined && body.error !== code)) {
+        if (result.status === 403)
+            throw new CliError("permission_denied", "当前操作权限不足。", "请核对设备与账号的权限；无法确定缺少哪个开关，不要自动重试。", 4, { http_status: 403 });
+        return;
+    }
+    const details = { http_status: result.status };
+    if (result.status === 400 && code === "knowledge_application_evidence_required")
+        throw new CliError(code, "未推进：需要一个已关联的项目和一句实际使用说明。", "和本人核对哪张卡、哪个项目、具体怎么用；没有项目先问是否新建或关联。不要自动重试。", 2, details);
+    if (result.status === 409 && code === "knowledge_application_project_unavailable")
+        throw new CliError(code, "未推进：这个项目不能作为本次应用的关联项目。", "请本人选择自己已关联的可用项目，不猜测原因或替换项目重试。", 2, details);
+    if (result.status === 403 && code === "capability_disabled" && !singleSwitchMetadata(body))
+        throw unverifiedSwitchError();
+    if (result.status === 403 && code === "capability_disabled" && body.required_capability === "write_project_update") {
+        // Agent advancement cannot jump levels: only an applied request can
+        // first cross this boundary. Never infer the card's current stage.
+        if (requestedStage !== "applied")
+            throw unverifiedSwitchError();
+        throw new CliError(code, "未推进：“写入项目进展”开关未开启。", "请本人到网页的 Agent 管理核对开关；不要重新授权、重试或移除应用说明来绕过权限。", 4, { ...details, required_capability: "write_project_update" });
+    }
+}
+export function apiError(result, requestKind = "write") {
+    const body = asRecord(result.body);
+    const raw = body?.code ?? body?.error;
+    if (result.status === 403 && body) {
+        if ((body.code !== undefined && body.code !== raw) || (body.error !== undefined && body.error !== raw))
+            return unverifiedSwitchError();
+        if (raw === "legal_consent_required")
+            return legalConsentRequiredError(result.status);
+        if (raw === "direct_public_write_forbidden")
+            return directPublicWriteError();
+        if (raw === "token_scope_insufficient")
+            return new CliError("token_scope_insufficient", "当前设备的权限范围不足。", "请本人在网页核对设备的只读或读写权限，不要重试来绕过限制。", 4, { http_status: 403 });
+        if (raw === "capability_disabled") {
+            const capability = body.required_capability;
+            if (typeof capability === "string" && Object.hasOwn(switchMessages, capability) && singleSwitchMetadata(body))
+                return new CliError("capability_disabled", switchMessages[capability], "请本人到网页的 Agent 管理核对并开启所需开关；不要重新授权或重试来绕过限制。", 4, { http_status: 403, required_capability: capability });
+            if (Object.hasOwn(body, "required_capability"))
+                return unverifiedSwitchError();
+            return new CliError("capability_disabled", "有账号能力开关未开启，但未能核实具体名称。", "请本人到网页的 Agent 管理核对；不要重新授权或重试来绕过限制。", 4, { http_status: 403 });
+        }
+    }
+    if (result.status === 409 && body && raw === "knowledge_stage_step_required"
+        && (body.code === undefined || body.code === raw) && (body.error === undefined || body.error === raw)) {
+        return knowledgeStageStepError(body);
+    }
+    if (result.status === 409 && raw === "duplicate_title") {
+        const missing = writeMissingSections(body?.missing_sections);
+        if (missing.length)
+            return new CliError("duplicate_title", "同名内容已存在，读取权限未开启，无法显示详情。", "请到网页核对内容或开启所需读取权限；不要重复创建或猜测已有内容的 ID。", 2, { http_status: 409, missing_sections: missing });
+    }
+    const code = typeof raw === "string" && codesByStatus[result.status]?.includes(raw) ? raw : result.status === 401 ? "unauthorized" : result.status === 403 ? "permission_denied" : result.status === 429 ? "rate_limited" : result.status >= 500 ? "server_error" : "request_rejected";
+    const exitCode = result.status === 401 ? 3 : result.status === 403 ? 4 : result.status === 429 ? 5 : result.status >= 500 ? 7 : 2;
+    const details = { http_status: result.status };
+    if (typeof result.retryAfterSeconds === "number" && Number.isFinite(result.retryAfterSeconds) && result.retryAfterSeconds >= 0)
+        details.retry_after_seconds = Math.min(86400, Math.ceil(result.retryAfterSeconds));
+    if (["write_failed", "write_target_not_found", "write_publication_failed"].includes(code) && body?.write_status === "failed") {
+        details.write_status = "failed";
+        if (typeof body.request_id === "string" && /^[A-Za-z0-9_-]{1,80}(?![\s\S])/.test(body.request_id))
+            details.request_id = body.request_id;
+        if (body.audit_pending === true && ["automatic", "manual_required"].includes(String(body.audit_recovery))) {
+            details.audit_pending = true;
+            details.audit_recovery = body.audit_recovery;
+        }
+    }
+    const authorizationActions = {
+        device_limit_reached: "设备数已达上限，请先在网页吊销不再使用的设备。",
+        device_issue_rate_limited: "设备签发过于频繁，请等待后由本人重新操作。",
+        authorization_consumed: "令牌已交付过，不能补领。请先在网页核对并吊销该设备，再重新授权。",
+        access_denied: "授权已被拒绝；只有本人需要接入时才重新发起。",
+        expired_token: "确认码已过期；需要接入时由本人重新发起。"
+    };
+    if (requestKind === "read" && result.status === 404) {
+        return new CliError(code, "未找到这条内容，或当前账号无法访问。", "请检查内容 ID，或先从项目、知识列表中查找可访问的内容。", exitCode, details);
+    }
+    if (requestKind === "read" && result.status === 400) {
+        return new CliError(code, "读取请求的参数无效。", "请核对命令参数、查询条件和内容 ID 后再查询。", exitCode, details);
+    }
+    return new CliError(code, "一间草堂请求未完成。", authorizationActions[code] ?? (result.status === 401 ? "请重新授权；不要输出或转发令牌。" : result.status === 403 ? "请在网页检查设备权限、账号能力或待确认事项。" : result.status === 429 ? "按返回的等待时间处理，不要自动重复写入。" : "先在网页核对实际结果，不要自动重试、换键或重新上传。"), exitCode, details);
+}
+function knowledgeStageStepError(body) {
+    let message = "知识长势只能逐级推进，不能跳级；本次未写入。";
+    let nextAction = "请在网页核对长势后按级推进；不要自动重试或自动补写中间级。";
+    const details = { http_status: 409 };
+    const missing = writeMissingSections(body.missing_sections);
+    if (missing.length && missing.every(row => row.section === "knowledge_result" || row.section === "draft_knowledge_result")) {
+        details.missing_sections = missing;
+        message += "读取权限未开启，无法显示当前级和下一可用级。";
+        nextAction = "请在一间草堂网页核对或开启所需读取权限；不要自动重试或自动补写中间级。";
+    }
+    else if (!Object.hasOwn(body, "missing_sections") || (Array.isArray(body.missing_sections) && body.missing_sections.length === 0)) {
+        // A partial, malformed or permission-projected response never licenses
+        // exposing one side of the pair. Rebuild only the five known adjacent enums.
+        const stages = KNOWLEDGE_GROWTH_STEPS.map(step => step.value);
+        const current = typeof body.current_status === "string" ? stages.indexOf(body.current_status) : -1;
+        if (current >= 0 && current < stages.length - 1 && body.next_status === stages[current + 1]) {
+            details.current_status = stages[current];
+            details.next_status = stages[current + 1];
+            details.current_growth = knowledgeGrowthMetadata(stages[current]);
+            details.next_growth = knowledgeGrowthMetadata(stages[current + 1]);
+            message += `当前第${current + 1}/5级，下一可用级为第${current + 2}/5级。`;
+        }
+    }
+    return new CliError("knowledge_stage_step_required", message, nextAction, 2, details);
+}
+export function expectOK(result, requestKind = "write") {
+    if (result.status < 200 || result.status >= 300)
+        throw apiError(result, requestKind);
+    return result;
+}
+/** Existing knowledge changes only; create has its own candidate/receipt rules. */
+export function expectKnowledgeChangeNotBlocked(result) {
+    const body = asRecord(result.body), code = body?.code ?? body?.error;
+    if (result.status === 422 && code === "content_blocked"
+        && (body?.code === undefined || body.code === code) && (body?.error === undefined || body.error === code)) {
+        throw new CliError("content_blocked", "本次公开变更被审核拦截，不代表用户输入格式错误；已有内容保留，本次公开变更未生效。", "请先到网页核对审核与内容；不要自动改写或重试，也不要推断内容已转为私有。", 2, { http_status: 422 });
+    }
+    return result;
+}
+/** Only the project title/summary PATCH adopts these fixed backend codes. */
+export function expectProjectTextOK(result) {
+    const body = asRecord(result.body);
+    const code = body?.code ?? body?.error;
+    if (result.status === 409 && (body?.code === "duplicate_title" || body?.error === "duplicate_title")) {
+        if (code === "duplicate_title" && (body?.code === undefined || body.code === code) && (body?.error === undefined || body.error === code)) {
+            const rows = writeMissingSections(body?.missing_sections);
+            const missing = rows.every(row => row.section === "project_result" || row.section === "draft_project_result") ? rows : [];
+            throw new CliError(code, missing.length ? "同名项目已存在，本次未保存。读取权限未开启，无法显示详情。" : "同名项目已存在，本次未保存。", "请先在网页核对同名项目，再由本人决定后续修改；不要自动重试。", 2, { http_status: 409, ...(missing.length ? { missing_sections: missing } : {}) });
+        }
+        // Conflicting aliases cannot activate the legacy missing-only duplicate
+        // explanation. Keep a generic conflict without adopting its metadata.
+        return expectOK({ ...result, body: undefined });
+    }
+    if ((body?.code === undefined || body.code === code) && (body?.error === undefined || body.error === code)) {
+        if (result.status === 400 && code === "invalid_project_text") {
+            throw new CliError(code, "项目标题或简介不符合要求，本次未保存。", "请检查去除首尾空白后的标题为2–80个Unicode字符、简介不超过280个Unicode字符，且非草稿项目简介必填；核对后再决定修改，不要自动重试。", 2, { http_status: 400 });
+        }
+        if (result.status === 409 && code === "project_changed") {
+            throw new CliError(code, "项目已发生变化，本次未写入。", "请先在网页核对项目当前内容和状态，再决定后续修改；不要自动重试。", 2, { http_status: 409 });
+        }
+        if (result.status === 503 && code === "moderation_unavailable") {
+            throw new CliError(code, "项目审核暂不可用，本次未保存。", "请由本人先在网页核对项目和审核状态，再决定后续操作；不要自动重试。", 7, { http_status: 503 });
+        }
+    }
+    return expectOK(result);
+}

package/dist/generated/knowledge-growth.js

@@ -0,0 +1,37 @@
+// Generated by scripts/generate-knowledge-growth.mjs from shared/knowledge-growth.json.
+// Do not edit this file directly; regenerate all three consumers together.
+export const KNOWLEDGE_GROWTH_STEPS = [
+    {
+        "value": "captured",
+        "label": "播种",
+        "description": "刚存下来，还没细看"
+    },
+    {
+        "value": "summarized",
+        "label": "生根",
+        "description": "看懂了，写下了自己的理解"
+    },
+    {
+        "value": "applied",
+        "label": "发芽",
+        "description": "在项目里真用上了"
+    },
+    {
+        "value": "reviewed",
+        "label": "开花",
+        "description": "回头看过，见到效果了"
+    },
+    {
+        "value": "templated",
+        "label": "结果",
+        "description": "固定成方法，以后反复用"
+    }
+];
+export function knowledgeGrowthMetadata(value) {
+    const index = KNOWLEDGE_GROWTH_STEPS.findIndex((step) => step.value === value);
+    if (index < 0)
+        return undefined;
+    const step = KNOWLEDGE_GROWTH_STEPS[index];
+    return { label: step.label, description: step.description, level: index + 1, total: 5 };
+}
+export const KNOWLEDGE_GROWTH_HELP = KNOWLEDGE_GROWTH_STEPS.map((step, index) => `${step.value}（${step.label}，${index + 1}/5：${step.description}）`).join("；");

package/dist/habit-day.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { OwnedTree } from "./installation.js";
+import { validDate } from "./query-validation.js";
+export const isResourceID = (value) => typeof value === "string" && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}(?![\s\S])/i.test(value);
+const formatDay = new Intl.DateTimeFormat("sv-SE", { timeZone: "Asia/Shanghai", year: "numeric", month: "2-digit", day: "2-digit" });
+// A single empty, date-named directory is the marker. There is no content or
+// credential file to parse, truncate or overwrite. The owned-tree checks pin
+// each filesystem operation to its verified parent; we only inspect this one
+// environment/owner. A crash, broken marker or unowned entry is never repaired.
+export async function startReportMode(home, environment, owner, now) {
+    try {
+        if (!isResourceID(owner) || !["production", "test"].includes(environment) || !Number.isFinite(now))
+            return "brief";
+        const day = formatDay.format(now);
+        if (!validDate(day))
+            return "brief";
+        const tree = new OwnedTree(home);
+        const account = createHash("sha256").update(owner.toLowerCase()).digest("hex");
+        const root = join(tree.home, ".caotang", "habit-days", environment, account), lockPath = join(root, ".lock");
+        const lock = await tree.createDirectory(lockPath);
+        if (!lock)
+            return "brief";
+        try {
+            const contents = await tree.list(root);
+            if (!contents || !contents.includes(".lock"))
+                return "brief";
+            const prior = contents.filter(entry => entry !== ".lock");
+            if (prior.length === 0) {
+                await tree.createDirectory(join(root, day));
+                return "brief";
+            }
+            if (prior.length !== 1 || !validDate(prior[0]) || prior[0] >= day)
+                return "brief";
+            const old = join(root, prior[0]);
+            const previous = await tree.directory(old, false, async (dirs) => dirs.at(-1).identity);
+            if (!previous || (await tree.list(old))?.length !== 0)
+                return "brief";
+            const dest = join(root, day), created = await tree.createDirectory(dest);
+            if (!created)
+                return "brief";
+            try {
+                await tree.removeDirectory(old, previous);
+            }
+            catch {
+                await tree.removeDirectory(dest, created);
+                return "brief";
+            }
+            return "detailed";
+        }
+        finally {
+            await tree.removeDirectory(lockPath, lock);
+        }
+    }
+    catch {
+        return "brief";
+    }
+}

package/dist/habit-read.js

@@ -0,0 +1,30 @@
+import { asRecord, CliError, expectOK, networkFailure } from "./errors.js";
+import { verifiedHabit } from "./habit-wire.js";
+export async function readHabit(ctx, start) {
+    let result;
+    try {
+        result = await ctx.api.request("/api/v1/agent/m1/" + (start ? "habit/start" : "rules"), { method: "GET", token: ctx.token });
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "network_error")
+            throw networkFailure(error, true);
+        throw error;
+    }
+    if (result.status === 401)
+        throw new CliError("unauthorized", "草堂授权已失效，未读到本次内容。", "先继续当前工作，请本人核对设备授权；不要自动重新授权。", 3, { http_status: 401 });
+    if (result.status >= 500)
+        throw new CliError("server_error", "草堂服务暂时不可用，未读到本次内容。", "先继续当前工作，稍后核对服务；不要反复重试或重新授权。", 7, { http_status: result.status });
+    expectOK(result, "read");
+    const body = verifiedHabit(result.body, start);
+    if (result.status !== 200 || !body)
+        throw new CliError("invalid_response", "草堂短读响应不完整，无法核实。", "先继续当前工作，不要把未读取的内容解释为没有资料。", 7, { http_status: result.status });
+    if (!start)
+        return { ...result, body };
+    let mode = "brief";
+    try {
+        if (ctx.startMode && body.rules !== null && !body.missing_sections.some(row => asRecord(row)?.reason === "read_failed"))
+            mode = await ctx.startMode(body.owner_id);
+    }
+    catch { /* Optional local state: stay brief. */ }
+    return { ...result, body: { ...body, briefing_mode: mode } };
+}

package/dist/habit-wire.js

@@ -0,0 +1,56 @@
+import { validDate as validDay } from "./query-validation.js";
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+const list = (value, n) => { if (!Array.isArray(value) || value.length > n)
+    throw Error(); return value; };
+const str = (v, max) => { if (typeof v !== "string" || [...v].length > max || v.includes("\0"))
+    throw Error(); return v; };
+const id = (v) => { const s = str(v, 128); if (!/^[a-z0-9_-]+(?![\s\S])/i.test(s))
+    throw Error(); return s; };
+const key = (v) => { const s = str(v, 64); if (!/^[a-z][a-z0-9_]*(?![\s\S])/.test(s))
+    throw Error(); return s; };
+const count = (v) => { if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0)
+    throw Error(); return v; };
+function rule(value) {
+    const r = record(value), text = str(r.text, 200);
+    // The Go writer rejects controls before trimming Unicode White_Space.
+    // A literal BOM is content, while NEL / lone surrogates cannot be stored.
+    if (/[\p{Cc}\u2028\u2029\uD800-\uDFFF]/u.test(text) || !text || text.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, "") !== text)
+        throw Error();
+    return { id: id(r.id), text, created_at: str(r.created_at, 64), updated_at: str(r.updated_at, 64) };
+}
+function pending(value) { const r = record(value), total = count(r.total), items = list(r.items, 3).map(value => { const p = record(value); return { id: id(p.id), action_type: key(p.action_type), summary: str(p.summary, 120) }; }); if (items.length > total)
+    throw Error(); return { total, items }; }
+function day(value) { const r = record(value); if (!validDay(r.date))
+    throw Error(); const total = count(r.total), items = list(r.items, 3).map(value => { const p = record(value); if (p.kind !== "project_update" && p.kind !== "checkin")
+    throw Error(); return { kind: p.kind, id: id(p.id), summary: str(p.summary, 120), ...(p.project_id === undefined ? {} : { project_id: id(p.project_id) }) }; }); if (items.length > total)
+    throw Error(); return { date: r.date, total, items }; }
+function step(value) { const r = record(value); return { id: id(r.id), project_id: id(r.project_id), summary: str(r.summary, 120), created_at: str(r.created_at, 64) }; }
+function gap(value) { const r = record(value); if (typeof r.reason !== "string" || !["capability_disabled", "read_failed", "community_disabled"].includes(r.reason))
+    throw Error(); return { section: key(r.section), ...(r.required_capability === undefined ? {} : { required_capability: key(r.required_capability) }), reason: r.reason }; }
+function official(value) { const r = record(value), total = count(r.unread_count), title = str(r.latest_title, 120); if ((total === 0 && title !== "") || (total > 0 && !title))
+    throw Error(); return { unread_count: total, latest_title: title }; }
+// Project the bounded wire fields rather than forwarding unknown content or
+// treating a missing section as empty. Unknown account truth wins over empty.
+export function verifiedHabit(value, start) {
+    try {
+        const r = record(value);
+        if (!start) {
+            if (r.limit !== 20 || r.max_chars !== 200)
+                return;
+            return { items: list(r.items, 20).map(rule), limit: 20, max_chars: 200 };
+        }
+        if (typeof r.partial !== "boolean" || !(typeof r.account_empty === "boolean" || r.account_empty === null))
+            return;
+        const rules = r.rules === null ? null : list(r.rules, 20).map(rule), p = r.pending === null ? null : pending(r.pending), days = r.recent_days === null ? null : list(r.recent_days, 3).map(day), next = r.next_step === null ? null : step(r.next_step), gaps = list(r.missing_sections, 32).map(gap);
+        const owner = typeof r.owner_id === "string" && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}(?![\s\S])/i.test(r.owner_id) ? r.owner_id : undefined;
+        const incomplete = rules === null || p === null || days === null || gaps.some(g => g.reason !== "community_disabled");
+        if ((incomplete || gaps.length > 0) && !r.partial)
+            return;
+        const contradicted = r.account_empty === true && (!!rules?.length || !!p?.total || !!days?.length || !!next);
+        return { ...(owner ? { owner_id: owner } : {}), ...(r.official_notices === undefined ? {} : { official_notices: r.official_notices === null ? null : official(r.official_notices) }), rules, pending: p, recent_days: days, next_step: next,
+            account_empty: !owner || r.partial || incomplete || contradicted ? null : r.account_empty, partial: r.partial, missing_sections: gaps };
+    }
+    catch {
+        return undefined;
+    }
+}