# https://github.com/JKHeadley/instar 项目说明书 生成时间：2026-06-21 02:55:39 UTC ## 目录 - [项目概览](#page-overview) - [Lib 模块](#page-scripts-lib) - [Src 模块](#page-feedback-front-src) - [Src 模块](#page-packages-threadline-mcp-src) ## 项目概览 ### 相关页面 相关主题：[Lib 模块](#page-scripts-lib)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) - [skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md) - [examples/scheduled-job/README.md](https://github.com/JKHeadley/instar/blob/main/examples/scheduled-job/README.md) - [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md) - [examples/telegram-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/telegram-agent/README.md) - [examples/multi-job-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/multi-job-agent/README.md) - [src/providers/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/README.md) - [src/providers/adapters/anthropic-interactive-pool/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/adapters/anthropic-interactive-pool/README.md) - [packages/threadline-mcp/package.json](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/package.json) - [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) - [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts)
# 项目概览 ## 一、项目定位与核心目标 Instar 定位为**自进化 AI 智能体的连贯性基础设施（Coherence infrastructure for self-evolving AI agents）**，运行在 Claude Code 或 Codex 订阅之上，无需额外的模型计费 [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md)。其根本目标是让一个 LLM 智能体不仅能执行任务，还能在跨会话、跨平台、跨机器的环境中保持身份、记忆、安全与决策一致性。 从社区历史来看，项目的演进路径非常清晰： - **v0.2.0** 引入 Intelligence Dispatch（情报广播）与更新回滚 [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md) - **v0.3.0** 引入行为钩子（如 `deferral-detector.js`，用于识别"I can't"、"want me to proceed?"等回避性措辞并注入尽职审查）[`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md) - **v0.3.1 – v0.3.6** 增强自诊断、更新频率、Telegram 中继修复 [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md) - **v0.17.14** 发布 Autonomy Guard、Coherence Gate 与 Threadline Protocol，被官方称为"上线以来最大版本，187 次提交，282 个 npm 版本" [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md) ## 二、技术栈与架构骨架 ### 2.1 包配置与运行时 Instar 以单一 npm 包 `instar` 发布，当前版本 `1.3.634` [`package.json`](https://github.com/JKHeadley/instar/blob/main/package.json)。包为 `type: "module"`，入口为编译后的 `dist/index.js`，CLI 二进制为 `dist/cli.js`，并附带 TypeScript 类型声明 [`package.json`](https://github.com/JKHeadley/instar/blob/main/package.json)。构建流程通过 `tsc` 编译后执行 `sign-instar-lockfile.mjs`，确保 lockfile 的可验证性 [`package.json`](https://github.com/JKHeadley/instar/blob/main/package.json)。 依赖矩阵涵盖了协议层、加密层与运行时层： | 关键依赖 | 用途 | |---------|------| | `@a2a-js/sdk` | Google Agent-to-Agent 协议 SDK | | `@huggingface/transformers` | 本地嵌入与模型推理 | | `@inquirer/prompts` | 交互式 CLI 提示 | | `@modelcontextprotocol/sdk` | MCP 工具协议 | | `@noble/ciphers` | Ed25519/X25519 加密原语 | 资料来源：[`package.json`](https://github.com/JKHeadley/instar/blob/main/package.json) ### 2.2 Provider 抽象层 `src/providers/README.md` 描述了一个**可移植的 Provider 适配器架构**，目标是在 Anthropic headless、Anthropic interactive pool、OpenAI Codex、local Ollama 等多种后端之间提供统一接口 [`src/providers/README.md`](https://github.com/JKHeadley/instar/blob/main/src/providers/README.md)。应用代码不应直接引用具体适配器，而是通过注册中心按能力解析： ```ts import { registry } from './providers/registry.js'; const session = await registry .resolve({ requires: ['agenticSessionHeadless', 'toolAccess'] }) .agenticSessionHeadless .start({ prompt, model: 'balanced' }); ``` 资料来源：[`src/providers/README.md`](https://github.com/JKHeadley/instar/blob/main/src/providers/README.md) `anthropic-interactive-pool` 适配器展示了一个具体实现：使用 OAuth 订阅令牌（`CLAUDE_CODE_OAUTH_TOKEN`，前缀 `sk-ant-oat-…`）进行订阅计费，API key 则回退到按量计费 [`src/providers/adapters/anthropic-interactive-pool/README.md`](https://github.com/JKHeadley/instar/blob/main/src/providers/adapters/anthropic-interactive-pool/README.md)。 ```mermaid graph LR App["应用层
(registry.resolve)"] --> Reg["Provider Registry"] Reg --> A["Anthropic Headless"] Reg --> B["Anthropic Interactive Pool"] Reg --> C["OpenAI Codex"] Reg --> D["Local Ollama"] A & B -->|OAuth/API| Claude["Claude 后端"] C --> Codex["Codex 后端"] D --> Ollama["本地模型"] ``` ## 三、能力矩阵与典型用法 ### 3.1 通信与多端消息 README 列出的功能涵盖 Telegram（每个 job 一个 forum topic）、WhatsApp（Baileys 或 Business API webhook）、iMessage（macOS Messages.app 数据库轮询 + `imsg` CLI）、Slack（八条 HTTP 路由） [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md)。`examples/telegram-agent/README.md` 演示了如何通过 BotFather 创建机器人、启用 forum topics、写入 `config.json`，并运行 `instar server start` [`examples/telegram-agent/README.md`](https://github.com/JKHeadley/instar/blob/main/examples/telegram-agent/README.md)。 ### 3.2 调度、记忆与技能 调度器基于标准 cron 语法（`minute hour day month weekday`），优先级支持 `low / normal / high / critical` [`examples/scheduled-job/README.md`](https://github.com/JKHeadley/instar/blob/main/examples/scheduled-job/README.md)。记忆体系是分层结构：`MEMORY.md`（磁盘文件全局持久）、会话级 SQLite + FTS5、滚动摘要、Evolution 系统（提案、学习、缺口追踪） [`examples/memory-agent/README.md`](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md)。 `skills/README.md` 将技能分为两类：纯客户端技能（`smart-web-fetch`、`command-guard`）和需 Instar 服务端的技能（`instar-scheduler`、`instar-session`、`instar-telegram`、`instar-identity`、`instar-feedback`），后者会在未安装时引导用户完成设置而非硬阻断 [`skills/README.md`](https://github.com/JKHeadley/instar/blob/main/skills/README.md)。 ### 3.3 Threadline Protocol（智能体间通信） Threadline 是项目最核心的子项目之一，提供基于 Ed25519 密钥的稳定身份、跨会话的对话历史，以及通过 `wss://threadline-relay.fly.dev/v1/connect` WebSocket 中继的发现机制 [`packages/threadline-mcp/src/server.ts`](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts)。其 MCP 工具集包括 `threadline_contacts`、`threadline_history`、`threadline_send`、`threadline_notes_view`、`threadline_notes_set` 等 [`packages/threadline-mcp/src/server.ts`](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts)。信任级别分为三档：`seen`（已发现）、`conversed`（已交互）、`trusted`（显式信任） [`packages/threadline-mcp/src/server.ts`](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts)。 ## 四、常见问题与运维注意事项 社区中已被识别的高频痛点值得在新用户部署前了解： 1. **Dashboard 单实例约束**：`dashboard/mandates.js` 第 248 行的 "open that machine's dashboard" 跳转在 `r.heldOnThisMachine === false` 时仍渲染，违反了"一机一仪表盘"的 UX 原则 [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md)（社区上下文 issue #1222）。 2. **自动更新静默卡死**：自动更新器曾记录 `lastAppliedVersion: 1.3.616` 但 `.instar/shadow-install/node_modules/instar/package.json` 仍为 `1.3.615`，即版本号被更新但文件未落盘 [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md)（社区上下文 issue #1221）。 3. **Telegram relay 缺失**：v0.3.6 之前的安装可能缺少 `telegram-reply.sh`，导致 relay 报 "Session respawned" 但无回复 [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md)。 用户在升级到 v0.17.14 后，应特别留意 Autonomy Guard 与 Coherence Gate 的引入对所有外发消息与决策的影响，并校验 Threadline 中继的注册状态 [`README.md`](https://github.com/JKHeadley/instar/blob/main/README.md)。 ## See Also - [`skills/instar-scheduler`](https://github.com/JKHeadley/instar/tree/main/skills/instar-scheduler) — 定时任务技能 - [`skills/instar-telegram`](https://github.com/JKHeadley/instar/tree/main/skills/instar-telegram) — 双向 Telegram 消息技能 - [`packages/threadline-mcp`](https://github.com/JKHeadley/instar/tree/main/packages/threadline-mcp) — 智能体间通信协议 - [inst.sh 官方文档](https://instar.sh) — 完整功能参考 --- ## Lib 模块 ### 相关页面 相关主题：[项目概览](#page-overview), [Src 模块](#page-feedback-front-src)
相关源码文件 以下源码文件用于生成本页说明： - [scripts/lib/classify-tier.mjs](https://github.com/JKHeadley/instar/blob/main/scripts/lib/classify-tier.mjs) - [scripts/lib/convergence-recognition.mjs](https://github.com/JKHeadley/instar/blob/main/scripts/lib/convergence-recognition.mjs) - [scripts/lib/dark-gate-attribution.js](https://github.com/JKHeadley/instar/blob/main/scripts/lib/dark-gate-attribution.js) - [scripts/lib/operator-surface.mjs](https://github.com/JKHeadley/instar/blob/main/scripts/lib/operator-surface.mjs) - [scripts/lib/pre-push-scope.mjs](https://github.com/JKHeadley/instar/blob/main/scripts/lib/pre-push-scope.mjs) - [scripts/lib/telegram-historian.mjs](https://github.com/JKHeadley/instar/blob/main/scripts/lib/telegram-historian.mjs) - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json)
# Lib 模块 `scripts/lib/` 目录是 Instar 仓库中脚本基础设施的"工具箱"，存放一组可被多个上层脚本（`npm run` 任务、`vitest` 推送门禁、`instar dev` 工作流）复用的纯函数与小型工具模块。该目录刻意保持 ESM/CommonJS 双风格：单入口工具（直接被 lint 调用的解析器）使用 `.js` 扩展名，而需要兼容旧测试运行器的更小脚本则使用 `.mjs` 后缀。资料来源：[scripts/lib/dark-gate-attribution.js:1-30]() ## 核心职责 Lib 模块并非独立运行时子系统，而是一组被下方脚本共用的解析器与归类器： | 工具 | 主要职责 | |------|---------| | `classify-tier.mjs` | 对风险/成本进行分级归类 | | `convergence-recognition.mjs` | 识别规范/接口的收敛点 | | `dark-gate-attribution.js` | 路径归属解析 + 注册表抽取（详见下节） | | `operator-surface.mjs` | 描述"操作面"边界 | | `pre-push-scope.mjs` | 推送前影响范围预检 | | `telegram-historian.mjs` | Telegram 历史归档辅助 | `package.json` 的 `scripts` 段通过 `node scripts/...` 直接调用这些工具，例如 `npm run test:smoke` 触发 `node scripts/pre-push-smoke.mjs`，由后者串联 `pre-push-scope.mjs` 等工具。资料来源：[package.json:14-22]() ## `dark-gate-attribution.js` 工作流 作为该目录中具有完整实现的代表模块，`dark-gate-attribution.js` 自述为"the path-attribution + registry-extraction core shared by `scripts/lint-dev-agent-dark-gate.js` (assertion C) and its golden-path drift-canary test"——其设计目标只有一个：让"lint 工具"与"金路径对照测试"在 **同一份代码** 上做归因，避免两份实现漂移。资料来源：[scripts/lib/dark-gate-attribution.js:25-28]() 模块导出三组实体： 1. **`VALID_CATEGORIES`（Set）**：固定枚举为 `destructive`、`cost-bearing`、`action-bearing`、`optional-integration`、`structural-stub`，作为"开发者暗门（dark gate）"的归因分类白名单。资料来源：[scripts/lib/dark-gate-attribution.js:5-11]() 2. **`codeOnly(line)`**：剥离 `//` 行注释；若整行都是注释（以 `*`、`//`、`/*` 起首），返回 `null`。它不处理块注释，目的明确：服务于"花括号深度计数"这一最简解析场景。资料来源：[scripts/lib/dark-gate-attribution.js:33-40]() 3. **`braceInString(code)`**：检测 *已剥离注释* 的代码行中是否存在落在字符串/模板字面量内部的 `{` 或 `}`，避免破坏 `codeOnly()` 之后的深度计数。逻辑为单趟扫描，遇到反斜杠跳过、转义后比对左右引号。资料来源：[scripts/lib/dark-gate-attribution.js:46-58]() `extractRegistry(absPath)` 进一步读取手写的 `devGatedFeatures.ts`（或同形文件），通过正则分别抽取两个数组字面量：第一个数组收集每个条目的 `configPath: '…'` 字符串；第二个数组解析"白名单豁免（exclusion）"四元组 `{ configPath, category, reason }`，供后续 lint 的 assertion C 使用。资料来源：[scripts/lib/dark-gate-attribution.js:15-22]() ```mermaid flowchart LR A[devGatedFeatures.ts] -->|fs.readFileSync| B(extractRegistry) B -->|configPath 列表| C[lint-dev-agent-dark-gate.js] B -->|exclusion 列表| C D[drift-canary test] -->|asserts on| B C -->|reports| E[CI / pre-push] ``` > **设计原则**：测试从不"自己重写一份解析器"，而是断言 *该模块* 的输出与手写期望表一致——这意味着若有人在 `devGatedFeatures.ts` 中误把 `//` 写进对象内部并被 `codeOnly` 误删，测试将立即失败。资料来源：[scripts/lib/dark-gate-attribution.js:26-28]() ## 与其他 Lib 模块的关系 `classify-tier.mjs`、`operator-surface.mjs`、`pre-push-scope.mjs` 等 `.mjs` 工具承担 **预检/分级** 角色，常在 `pre-push` 链路中被串联调用；`convergence-recognition.mjs` 与 `telegram-historian.mjs` 则在更上层的"演化与历史"工作流里充当判定器或归档器。Lib 模块统一遵守两条约束：(a) 不引入新依赖，凡需 Node 内置即可完成的任务优先使用 `node:fs`、`node:crypto` 等标准库；(b) 不持有可变全局状态，便于在 `vitest` 推送配置下被并发调用。资料来源：[package.json:24-26]() ## 使用与故障模式 - **调用入口**：所有 Lib 模块都通过 `node scripts/.mjs` 或 `node scripts/.js` 进入；它们不会出现在 `package.json` 的 `bin` 中，因此不会被作为 CLI 直接暴露。 - **典型失败**：`dark-gate-attribution.js` 依赖稳定的源文件形状（`export const X = [ … ];`），一旦有人把数组改写成 `as const` 元组或对象，正则将匹配失败，lint 报"未注册 configPath"。该行为是有意为之——任何破坏稳定契约的修改都必须被开发者主动显式说明。 - **常见误用**：在 `codeOnly` 之后直接对对象字面量求深度，会得到错误结果；正确做法是先过 `braceInString` 排除字符串内的花括号。 ## See Also - [Agent Skills 总览](https://instar.sh/skills/) — 仓库根 `skills/` 下的 Agent Skills 开放标准实现 - [构建与发布流程](https://instar.sh/reference/build/) — `package.json` 中 `build` 脚本串联 `generate:manifest` + `tsc` + lockfile 签名 - [预检与推送门禁](https://instar.sh/reference/pre-push/) — `test:smoke` 调用的预检链 --- ## Src 模块 ### 相关页面 相关主题：[Lib 模块](#page-scripts-lib), [Src 模块](#page-packages-threadline-mcp-src)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) - [src/providers/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/README.md) - [src/providers/adapters/anthropic-interactive-pool/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/adapters/anthropic-interactive-pool/README.md) - [src/threadline/client/RegistryRestClient.ts](https://github.com/JKHeadley/instar/blob/main/src/threadline/client/RegistryRestClient.ts) - [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) - [packages/threadline-mcp/package.json](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/package.json) - [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts) - [src/redteam/packs/README.md](https://github.com/JKHeadley/instar/blob/main/src/redteam/packs/README.md) - [scripts/lib/dark-gate-attribution.js](https://github.com/JKHeadley/instar/blob/main/scripts/lib/dark-gate-attribution.js)
# Src 模块 ## 概览与定位 `src/` 目录是 Instar 项目的核心代码载体，承载了 Instar 框架在自进化智能体（self-evolving AI agent）场景下的所有关键子系统。依据 [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) 的功能矩阵，`src/` 下涵盖了 Telegram/WhatsApp/iMessage/Slack 等多渠道消息、Threadline 多智能体协议、Coherence Gate、Coherence Memory、Evolution System、Multi-Machine 加密同步等全部运行时能力。 在打包层面，[package.json](https://github.com/JKHeadley/instar/blob/main/package.json) 声明主入口为 `dist/index.js`、类型入口为 `dist/index.d.ts`，CLI 通过 `dist/cli.js` 暴露。`build` 脚本串联 `generate-builtin-manifest.cjs` → `tsc` → `chmod` → `sign-instar-lockfile.mjs`，并通过 `files` 字段将 `src/templates`、`src/data`、`src/threadline/data`、`src/scaffold` 等运行时数据目录随包分发。 ## 主要子系统结构 ### Providers（可移植适配层） [src/providers/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/README.md) 描述了按阶段分层的适配器树：Phase 3a 的 `anthropic-headless`、Phase 3b 的 `anthropic-interactive`、Phase 4 的 `openai-codex`、Phase 6 的 `local-ollama`。通用原语被划分到 `primitives/transport`、`primitives/capability`、`primitives/observability`、`primitives/control`、`primitives/integration` 五个包；具体适配器通过 `registry.register({ id, capabilities, factory })` 注册，能力由 `CapabilityFlag[]` 数组声明。 [src/providers/adapters/anthropic-interactive-pool/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/adapters/anthropic-interactive-pool/README.md) 进一步展示了 Phase 3b 的池化交互适配器，工厂函数 `createAnthropicInteractivePoolAdapter` 接受 `poolSize`、`maxMessagesPerSession`、`maxIdleMinutes` 等参数，订阅凭据从 `CLAUDE_CODE_OAUTH_TOKEN`（前缀 `sk-ant-oat-…`）回退到 API Key。 ### Threadline（智能体间通信协议） Threadline 子系统由 `src/threadline/` 与外部包 `packages/threadline-mcp` 共同实现。[packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) 暴露了 `threadline_*` 系列的 MCP 工具，持久状态位于 `~/.threadline/identity.json`（Ed25519 密钥对）等文件中。[packages/threadline-mcp/package.json](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/package.json) 声明其依赖 `@modelcontextprotocol/sdk`，并要求 Node ≥ 20。 [src/threadline/client/RegistryRestClient.ts](https://github.com/JKHeadley/instar/blob/main/src/threadline/client/RegistryRestClient.ts) 是注册中心的轻量 REST 客户端，它先通过 WebSocket 与 relay 鉴权换取 JWT，再以 REST 调用注册表；构造时根据 `wss:`/`ws:` 协议自动推导 `baseUrl`。 ### Feedback Front 与 Redteam [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts) 是面向 Vercel 部署的反馈入口处理器，引入 `src/feedback-factory/receiver/defense.js`（签名校验、Honeypot 检测、限流）和 `BlobInboxStore`，使用模块级 `RateLimiter` 保证单实例在多次调用间的限流状态。 [src/redteam/packs/README.md](https://github.com/JKHeadley/instar/blob/main/src/redteam/packs/README.md) 描述了 MTP Red-Team Harness 的载荷引用协议：编排器只处理 `{path, sha256}` 引用，永不内联载荷文本，以避免攻击性内容写入长生命周期的智能体会话。 ## 架构与运行时关系 ```mermaid flowchart LR CLI[dist/cli.js\ninstar 命令] --> Server[Server + Jobs] Server --> Providers[src/providers\nregistry.resolve] Providers --> Headless[anthropic-headless] Providers --> Pool[anthropic-interactive-pool] Server --> Threadline[src/threadline\n+ packages/threadline-mcp] Threadline --> Relay[wss://threadline-relay\nRegistryRestClient] Server --> Feedback[src/feedback-factory\nfeedback-front] Server --> Redteam[src/redteam/packs\nMTP Harness] Scripts[scripts/lib] -.-> Build[tsc + sign-instar-lockfile] Build --> Dist[dist/ + signed lockfile] ``` ## 内部支撑脚本 [scripts/lib/dark-gate-attribution.js](https://github.com/JKHeadley/instar/blob/main/scripts/lib/dark-gate-attribution.js) 抽出被 `scripts/lint-dev-agent-dark-gate.js` 与金路径漂移金丝雀测试共用的归因核心，并提供 `extractRegistry()` 通过正则解析手写的 `devGatedFeatures.ts`。`codeOnly()` 剥除行注释、`braceInString()` 检测字符串内大括号对深度计数器造成的失同步；导出 `VALID_CATEGORIES` 包含 `destructive / cost-bearing / action-bearing / optional-integration / structural-stub`。该模块的设计原则是「lint 与测试通过构造保持一致」，确保断言 C 与金丝雀对同一份解析器输出达成共识。 ## 常见误区与失败模式 - **Auto-updater 静默卡死**：社区报告 [Issue #1221](https://github.com/JKHeadley/instar/issues/1221) 显示 `lastAppliedVersion` 在文件未真正落盘的情况下被记录，导致 `node_modules/instar/package.json` 与元数据不一致。修复需要在 `scripts/lib/` 的升级链路中新增「落盘校验」步骤。 - **Dashboard 跨机越界**：[Issue #1222](https://github.com/JKHeadley/instar/issues/1222) 指出 `dashboard/mandates.js` 在审批面板中仍会出现「open that machine's dashboard」提示，违反「一台机器一个 dashboard」UX 规约；该处路由需在 `r.heldOnThisMachine === false` 时仅展示挂起标记，而非跳转链接。 ## 另见 - [Threadline Protocol Wiki](#) - [Providers / Adapter Portability](#) - [Feedback Factory](#) - [Red-Team Harness (EXO 3.0 G7)](#) - [Release Notes v0.17.14](https://github.com/JKHeadley/instar/releases/tag/v0.17.14) --- ## Src 模块 ### 相关页面 相关主题：[Src 模块](#page-feedback-front-src)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) - [src/providers/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/README.md) - [src/providers/adapters/anthropic-interactive-pool/README.md](https://github.com/JKHeadley/instar/blob/main/src/providers/adapters/anthropic-interactive-pool/README.md) - [src/threadline/client/RegistryRestClient.ts](https://github.com/JKHeadley/instar/blob/main/src/threadline/client/RegistryRestClient.ts) - [src/redteam/packs/README.md](https://github.com/JKHeadley/instar/blob/main/src/redteam/packs/README.md) - [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) - [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts) - [scripts/lib/dark-gate-attribution.js](https://github.com/JKHeadley/instar/blob/main/scripts/lib/dark-gate-attribution.js)
# Src 模块 ## 模块总览 `src/` 目录是 Instar 项目的核心实现层，承载了除 CLI 入口（`dist/cli.js`）和模板资源（`src/templates/`、`src/data/`、`src/threadline/data/`）之外的全部应用逻辑。从 `package.json` 的 `files` 字段可见，发布到 npm 的产物中明确包含 `src/templates`、`src/data`、`src/threadline/data`、`src/scaffold` 等子目录，表明 `src/` 同时也是运行时静态资源的承载者 资料来源：[package.json:55-66]()。 在 v0.17.14 的发布说明中，Threadline 协议、Autonomy Guard、Coherence Gate 等核心特性都以 `src/` 为主要实现位置；社区关注的 Telegram 消息注入修复、自检机制与行为挂钩等亦分别落在该树中的 `feedback-factory/`、`server.ts`、`hooks/` 等位置。 ## 核心子模块 ### 1. providers —— 可插拔适配器层 `src/providers/` 定义了 Instar 的“提供者可移植性”框架。其 README 指出，该层按照 phase 拆分适配器：`anthropic-interactive-pool/`（Phase 3b）、`openai-codex/`（Phase 4）、`local-ollama/`（Phase 6）资料来源：[src/providers/README.md]()。 应用代码通过 `registry.resolve({ requires: [...] })` 拿到能力句柄，而不是直接 import 具体适配器。这种“按能力路由”模型与 v0.17.14 中强调的 EXO 3.0 readiness scoring 直接呼应：路由策略（Phase 5）会根据能力可用性与配额状态决定具体适配器 资料来源：[src/providers/README.md]()。 `anthropic-interactive-pool` 是其中已经实现并通过 OAuth 订阅计费的适配器。它通过 `poolSize`、`maxMessagesPerSession`、`maxIdleMinutes` 等参数控制会话池行为，并优先使用 `CLAUDE_CODE_OAUTH_TOKEN`（前缀 `sk-ant-oat-…`）进行订阅计费，回退到 API key 资料来源：[src/providers/adapters/anthropic-interactive-pool/README.md]()。 ### 2. threadline —— 代理间协议 `src/threadline/` 是 Threadline 协议的主实现目录。`RegistryRestClient.ts` 是其中较为轻量的 REST 客户端：先通过 WebSocket 连接 relay 取得 JWT，再以 Ed25519 身份访问注册表 资料来源：[src/threadline/client/RegistryRestClient.ts:1-58]()。 与之并行的 `packages/threadline-mcp/src/server.ts` 则暴露 MCP 工具集，包括 `threadline_contacts`、`threadline_notes_view`、`threadline_notes_set` 等。状态目录默认为 `~/.threadline/`，其中 `identity.json` 保存 Ed25519 密钥对，从而保证代理 ID 在不同会话间保持稳定 资料来源：[packages/threadline-mcp/src/server.ts:38-52]()。 ### 3. redteam —— MTP 攻防演练 `src/redteam/packs/` 是 EXO 3.0 G7 对应的 red-team harness。它采用“通过路径与 sha256 引用 payload”的协议：仓库仅提交 `L0.md`、`L1.md` 两个低强度 payload，更高强度的 `L2.md`（motivated）和 `L3.md`（engineered）在本地专用会话中临场创作，并通过 `.gitignore` 隔离，避免攻击文本污染长寿命的代理会话 资料来源：[src/redteam/packs/README.md:1-15]()。 编排器自身只读取 `{path, sha256}`，从不直接读取 payload 内容；机械 runner 在发送时才真正读取文件并校验哈希，从而避免 CMT-1115 中出现的“把攻击 payload 内联进会话导致 AUP-rejection 循环、永久楔住会话”的事故 资料来源：[src/redteam/packs/README.md:3-7]()。 ### 4. feedback-factory 与周边 虽然主要处理器不在本批抓取文件中，但 `feedback-front/src/feedback.ts` 直接相对导入 `../../src/feedback-factory/receiver/defense.js`、`handlers.js`、`BlobInboxStore.js` 等模块，说明 `src/feedback-factory/` 是反馈管线后端的承载目录，前端仅作为薄壳存在 资料来源：[feedback-front/src/feedback.ts:8-14]()。 ## 工具脚本与 lint 协同 `scripts/lib/dark-gate-attribution.js` 抽出“路径归属 + 注册表提取”核心，供 `lint-dev-agent-dark-gate.js`（断言 C）和 golden-path drift-canary 测试共享，避免 lint 与测试出现双实现分歧 资料来源：[scripts/lib/dark-gate-attribution.js:1-14]()。该函数通过正则匹配 `devGatedFeatures.ts` 中的 `configPath` 与 `DARK_GATE_EXCLUSIONS` 段落，使其在纯 JS 环境中也能复用 TS 注册表的内容。 ## 架构示意 ```mermaid flowchart LR CLI["dist/cli.js
CLI 入口"] --> Registry["providers/registry
按能力路由"] Registry --> Pool["anthropic-interactive-pool
Phase 3b"] Registry --> Codex["openai-codex
Phase 4"] Registry --> Ollama["local-ollama
Phase 6"] CLI --> Threadline["threadline/
RegistryRestClient + 状态目录"] Threadline --> Relay["wss://threadline-relay.fly.dev"] CLI --> Feedback["feedback-factory/receiver"] CLI --> RedTeam["redteam/packs
payload by sha256"] CLI --> Scripts["scripts/lib
dark-gate-attribution"] ``` ## 使用模式与失效模式 - **运行时静态资源**：`src/templates/`、`src/data/`、`src/threadline/data/` 都会随 npm 发布一起被打包，运行期无需额外下载 资料来源：[package.json:55-66]()。 - **代理能力解耦**：业务代码不应 `import` 具体适配器，而应通过 `registry.resolve({ requires: [...] })` 取能力，从而在 Phase 5 路由策略上线后无须改动调用方 资料来源：[src/providers/README.md]()。 - **代理间身份**：`~/.threadline/identity.json` 是 Ed25519 长期身份；删除该文件等同于重置代理身份，会破坏 Threadline 上其他代理对该 ID 的信任记录 资料来源：[packages/threadline-mcp/src/server.ts:38-52]()。 - **red-team payload 隔离**：未本地创作 `L2/L3` payload 时，runner 会拒绝发送并以 `PENDING-LOCAL-AUTHOR` 状态阻断，这是有意为之的护栏 资料来源：[src/redteam/packs/README.md:11-15]()。 - **自动化更新楔住风险**：社区 issue #1221 指出 `lastAppliedVersion` 与磁盘文件版本可能不一致，提示任何依赖“已记录版本”的自动化逻辑都应同时验证 on-disk 文件落地。 ## 参见 - Threadline 协议发布说明：[v0.17.14](https://github.com/JKHeadley/instar/releases/tag/v0.17.14) - Telegram relay 与消息注入修复：[v0.3.6](https://github.com/JKHeadley/instar/releases/tag/v0.3.6) - 自检任务（每 2 小时一次）：[v0.3.2](https://github.com/JKHeadley/instar/releases/tag/v0.3.2) - 仪表盘权限面板一次仪表盘约束：[issue #1222](https://github.com/JKHeadley/instar/issues/1222) --- --- ## Doramagic 踩坑日志 项目：JKHeadley/instar 摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：auto-updater: records lastAppliedVersion without verifying files landed on disk → silent deploy wedge。 ## 1. 安装坑 · 来源证据：auto-updater: records lastAppliedVersion without verifying files landed on disk → silent deploy wedge - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：auto-updater: records lastAppliedVersion without verifying files landed on disk → silent deploy wedge - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/JKHeadley/instar/issues/1221 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 2. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/JKHeadley/instar | host_targets=claude_code, claude, chatgpt ## 3. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/JKHeadley/instar | README/documentation is current enough for a first validation pass. ## 4. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/JKHeadley/instar | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/JKHeadley/instar | no_demo; severity=medium ## 6. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/JKHeadley/instar | no_demo; severity=medium ## 7. 安全/权限坑 · 来源证据：dashboard mandates: line-248 'open that machine's dashboard' punt violates one-dashboard on the agent-asks-approval path - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：dashboard mandates: line-248 'open that machine's dashboard' punt violates one-dashboard on the agent-asks-approval path - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/JKHeadley/instar/issues/1222 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/JKHeadley/instar | issue_or_pr_quality=unknown ## 9. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/JKHeadley/instar | release_recency=unknown