一、项目定位与核心目标

Instar 定位为自进化 AI 智能体的连贯性基础设施（Coherence infrastructure for self-evolving AI agents），运行在 Claude Code 或 Codex 订阅之上，无需额外的模型计费 README.md。其根本目标是让一个 LLM 智能体不仅能执行任务，还能在跨会话、跨平台、跨机器的环境中保持身份、记忆、安全与决策一致性。

从社区历史来看，项目的演进路径非常清晰：

• v0.2.0 引入 Intelligence Dispatch（情报广播）与更新回滚 README.md
• v0.3.0 引入行为钩子（如 deferral-detector.js，用于识别"I can't"、"want me to proceed?"等回避性措辞并注入尽职审查）README.md
• v0.3.1 – v0.3.6 增强自诊断、更新频率、Telegram 中继修复 README.md
• v0.17.14 发布 Autonomy Guard、Coherence Gate 与 Threadline Protocol，被官方称为"上线以来最大版本，187 次提交，282 个 npm 版本" README.md

二、技术栈与架构骨架

2.1 包配置与运行时

Instar 以单一 npm 包 instar 发布，当前版本 1.3.634 package.json。包为 type: "module"，入口为编译后的 dist/index.js，CLI 二进制为 dist/cli.js，并附带 TypeScript 类型声明 package.json。构建流程通过 tsc 编译后执行 sign-instar-lockfile.mjs，确保 lockfile 的可验证性 package.json。

依赖矩阵涵盖了协议层、加密层与运行时层：

资料来源：package.json

2.2 Provider 抽象层

src/providers/README.md 描述了一个可移植的 Provider 适配器架构，目标是在 Anthropic headless、Anthropic interactive pool、OpenAI Codex、local Ollama 等多种后端之间提供统一接口 src/providers/README.md。应用代码不应直接引用具体适配器，而是通过注册中心按能力解析：

import { registry } from './providers/registry.js';
const session = await registry
  .resolve({ requires: ['agenticSessionHeadless', 'toolAccess'] })
  .agenticSessionHeadless
  .start({ prompt, model: 'balanced' });

资料来源：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。

graph LR
    App["应用层<br/>(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。examples/telegram-agent/README.md 演示了如何通过 BotFather 创建机器人、启用 forum topics、写入 config.json，并运行 instar server start examples/telegram-agent/README.md。

3.2 调度、记忆与技能

调度器基于标准 cron 语法（minute hour day month weekday），优先级支持 low / normal / high / critical examples/scheduled-job/README.md。记忆体系是分层结构：MEMORY.md（磁盘文件全局持久）、会话级 SQLite + FTS5、滚动摘要、Evolution 系统（提案、学习、缺口追踪） 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。

3.3 Threadline Protocol（智能体间通信）

Threadline 是项目最核心的子项目之一，提供基于 Ed25519 密钥的稳定身份、跨会话的对话历史，以及通过 wss://threadline-relay.fly.dev/v1/connect WebSocket 中继的发现机制 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。信任级别分为三档：seen（已发现）、conversed（已交互）、trusted（显式信任） packages/threadline-mcp/src/server.ts。

四、常见问题与运维注意事项

社区中已被识别的高频痛点值得在新用户部署前了解：

1. Dashboard 单实例约束：dashboard/mandates.js 第 248 行的 "open that machine's dashboard" 跳转在 r.heldOnThisMachine === false 时仍渲染，违反了"一机一仪表盘"的 UX 原则 README.md（社区上下文 issue #1222）。
2. 自动更新静默卡死：自动更新器曾记录 lastAppliedVersion: 1.3.616 但 .instar/shadow-install/node_modules/instar/package.json 仍为 1.3.615，即版本号被更新但文件未落盘 README.md（社区上下文 issue #1221）。
3. Telegram relay 缺失：v0.3.6 之前的安装可能缺少 telegram-reply.sh，导致 relay 报 "Session respawned" 但无回复 README.md。

用户在升级到 v0.17.14 后，应特别留意 Autonomy Guard 与 Coherence Gate 的引入对所有外发消息与决策的影响，并校验 Threadline 中继的注册状态 README.md。

See Also

• skills/instar-scheduler — 定时任务技能
• skills/instar-telegram — 双向 Telegram 消息技能
• packages/threadline-mcp — 智能体间通信协议
• inst.sh 官方文档 — 完整功能参考

scripts/lib/ 目录是 Instar 仓库中脚本基础设施的"工具箱"，存放一组可被多个上层脚本（npm run 任务、vitest 推送门禁、instar dev 工作流）复用的纯函数与小型工具模块。该目录刻意保持 ESM/CommonJS 双风格：单入口工具（直接被 lint 调用的解析器）使用 .js 扩展名，而需要兼容旧测试运行器的更小脚本则使用 .mjs 后缀。资料来源：scripts/lib/dark-gate-attribution.js:1-30

核心职责

Lib 模块并非独立运行时子系统，而是一组被下方脚本共用的解析器与归类器：

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

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/<caller>.mjs 或 node scripts/<caller>.js 进入；它们不会出现在 package.json 的 bin 中，因此不会被作为 CLI 直接暴露。
• 典型失败：dark-gate-attribution.js 依赖稳定的源文件形状（export const X = [ … ];），一旦有人把数组改写成 as const 元组或对象，正则将匹配失败，lint 报"未注册 configPath"。该行为是有意为之——任何破坏稳定契约的修改都必须被开发者主动显式说明。
• 常见误用：在 codeOnly 之后直接对对象字面量求深度，会得到错误结果；正确做法是先过 braceInString 排除字符串内的花括号。

See Also

• Agent Skills 总览 — 仓库根 skills/ 下的 Agent Skills 开放标准实现
• 构建与发布流程 — package.json 中 build 脚本串联 generate:manifest + tsc + lockfile 签名
• 预检与推送门禁 — test:smoke 调用的预检链

概览与定位

src/ 目录是 Instar 项目的核心代码载体，承载了 Instar 框架在自进化智能体（self-evolving AI agent）场景下的所有关键子系统。依据 README.md 的功能矩阵，src/ 下涵盖了 Telegram/WhatsApp/iMessage/Slack 等多渠道消息、Threadline 多智能体协议、Coherence Gate、Coherence Memory、Evolution System、Multi-Machine 加密同步等全部运行时能力。

在打包层面，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 描述了按阶段分层的适配器树：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 进一步展示了 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 暴露了 threadline_* 系列的 MCP 工具，持久状态位于 ~/.threadline/identity.json（Ed25519 密钥对）等文件中。packages/threadline-mcp/package.json 声明其依赖 @modelcontextprotocol/sdk，并要求 Node ≥ 20。

src/threadline/client/RegistryRestClient.ts 是注册中心的轻量 REST 客户端，它先通过 WebSocket 与 relay 鉴权换取 JWT，再以 REST 调用注册表；构造时根据 wss:/ws: 协议自动推导 baseUrl。

Feedback Front 与 Redteam

feedback-front/src/feedback.ts 是面向 Vercel 部署的反馈入口处理器，引入 src/feedback-factory/receiver/defense.js（签名校验、Honeypot 检测、限流）和 BlobInboxStore，使用模块级 RateLimiter 保证单实例在多次调用间的限流状态。

src/redteam/packs/README.md 描述了 MTP Red-Team Harness 的载荷引用协议：编排器只处理 {path, sha256} 引用，永不内联载荷文本，以避免攻击性内容写入长生命周期的智能体会话。

架构与运行时关系

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 抽出被 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 显示 lastAppliedVersion 在文件未真正落盘的情况下被记录，导致 node_modules/instar/package.json 与元数据不一致。修复需要在 scripts/lib/ 的升级链路中新增「落盘校验」步骤。
• Dashboard 跨机越界：Issue #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

Pitfall Log / 踩坑日志

项目：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