项目定位与核心能力

liteagents 的核心定位是"让 AI 代理记住用户真正在意的东西"。它通过 /friction（记录用户摩擦点）与 /remember（沉淀为长期记忆）两条命令驱动记忆流水线，避免机器代理信号污染热记忆（hot memory），并确保抗原来源于用户实际说过/反馈的内容（按内容与短语重叠聚类）。

资料来源：README.md:1-40

该项目主要面向以下场景：

• 当 AI 代理重复犯错时，快速捕获"用户反应"作为反馈信号；
• 在多代理、多工具环境中统一记忆格式，避免工具间认知漂移；
• 通过记忆即代码（memory-as-code）方式，让团队对代理行为拥有可审计的版本控制。

包结构与多工具适配

从 package.json 与 cli.js 的设计来看，liteagents 同时向四个目标工具包发布相同的记忆流水线逻辑：claude、opencode、ampcode、droid。这意味着一次升级会同步应用到全部四种工具，降低了用户在不同工具间切换时的认知负担。

资料来源：package.json:1-60、cli.js:1-120

下表展示了该多包策略的关键设计要点：

资料来源：postinstall.js:1-80、CHANGELOG.md:1-50

安装与运行时架构

postinstall.js 在 npm 安装阶段执行，负责把 liteagents 的记忆钩子注册到目标工具的设置中。这一设计使记忆系统对终端用户"零配置"即可启用，安装即生效。

运行时架构可概括为三层：

1. 捕获层：/friction 命令接收用户对代理输出的反应（文字否定、修改、重写等）；
2. 聚类层：按用户实际表述内容与短语重叠度对反应进行聚类，生成抗原候选；
3. 沉淀层：/remember 将已校验的抗原写入长期记忆，供后续会话通过上下文检索调用。

资料来源：cli.js:40-160、CLAUDE.md:1-60

v2.9.0 关键改动与社区反馈

v2.9.0 的核心改动是 重做 /friction → /remember 流水线，目标是解决摩擦记忆"毒化"热记忆的旧问题。社区中讨论最多的痛点是：旧版本会以工具内部信号作为抗原来源，导致用户实际反馈被覆盖；新版本则要求抗原必须来自用户原话或原意（content/phrase overlap），从而显著提升记忆的精确性。

资料来源：CHANGELOG.md:1-40

该版本同时在四个工具包中以完全一致的逻辑落地，避免了"在 Claude 中记忆有效、在 Droid 中失效"的工具漂移问题——这是社区在多个 issue 中反复提出的诉求。

资料来源：README.md:20-60、CLAUDE.md:10-50

适用与不适用场景

适用于：跨会话的代理行为调优、团队共享记忆、CI 中校验记忆合规性。不适用于：纯一次性脚本、对延迟敏感的实时推理（聚类会带来额外开销）、以及不希望记忆被持久化的隐私敏感场景。

资料来源：package.json:20-80

概述与范围

liteagents 仓库通过 packages/ 下的四个并行分发包（claude、opencode、ampcode、droid）提供统一的智能体与命令资产。每个分发包在结构上对齐：均包含 agents/ 目录与 commands/ 目录（部分包附带 skills/ 目录），从而支持在不同的 IDE / CLI 工具环境中以零修改方式复用同一套语义。v2.9.0 起，跨四包的内容（如 /friction → /remember 内存管线）以"完全相同"的方式应用，确保迁移成本为零。资料来源：packages/claude/agents/orchestrator.md:1-1

整个项目共登记 11 个智能体（agents）与 22 个命令 / 技能（commands + skills）。智能体聚焦"长期角色与多步流水线"，命令 / 技能聚焦"短时触发的用户意图"。这种"角色 ↔ 命令"分离模式，使得复杂任务可在 orchestrator 调度下分解为多个步骤，而每个步骤的入口则通过轻量命令暴露给最终用户。

智能体清单（11 个 Agents）

智能体按"PRD → 任务分解 → 任务执行"三段式编号约定组织，并以 orchestrator 作为顶层调度。

资料来源：packages/claude/agents/1-create-prd.md:1-1、packages/claude/agents/2-generate-tasks.md:1-1、packages/claude/agents/3-process-task-list.md:1-1

四个分发包各自维护一份等价副本，因此 orchestrator 在 claude、opencode、ampcode、droid 中分别存在，但语义保持一致。资料来源：packages/opencode/agents/orchestrator.md:1-1、packages/ampcode/agents/orchestrator.md:1-1、packages/droid/agents/orchestrator.md:1-1

命令与技能清单（22 个 Commands / Skills）

命令层提供面向用户的轻量入口，按主题聚合为三类：

• 内存管线（Memory pipeline）：以 /remember 为核心，旧版 /friction 自 v2.9.0 起统一收敛至 /remember，避免热内存被噪声污染，并通过"用户实际说过的话"作为抗原种子。资料来源：packages/claude/commands/remember.md:1-1
• 暂存与回溯（Stash & Recall）：/stash 用于暂存上下文片段，便于跨会话复用。
• 技能包（Skills）：在 skills/ 目录下以领域能力（如代码审查、文档生成）形式分发，由命令按需调用。

资料来源：packages/claude/commands/stash.md:1-1、packages/opencode/commands/remember.md:1-1、packages/ampcode/commands/remember.md:1-1、packages/droid/commands/remember.md:1-1

每个分发包都维护一份 commands/remember.md，并在 v2.9.0 中同步刷新其内部对抗原聚类（content / phrase overlap）的描述，保证四个工具行为一致。

工作流与一致性约束

flowchart LR
  U[用户输入] --> O[orchestrator]
  O --> P1[1-create-prd]
  P1 --> P2[2-generate-tasks]
  P2 --> P3[3-process-task-list]
  U -.触发.-> C1[/remember/]
  U -.触发.-> C2[/stash/]
  C1 --> M[(热内存)]
  P3 --> M

智能体与命令通过共享内存相互耦合：命令 /remember 写入的"用户原话"片段会被后续 3-process-task-list 步骤检索并作为执行依据；orchestrator 始终处于调用栈顶端，确保任何命令触发的副作用都会被纳入下一步计划。资料来源：packages/claude/agents/orchestrator.md:1-1、packages/claude/commands/remember.md:1-1

版本演进与社区关注点

社区讨论集中在两条主线：

1. 抗原污染问题：v2.9.0 之前 /friction 会把机器代理的代理反应混入抗原，导致热内存被噪声主导；现版本统一改为基于"用户实际说过的话"做聚类。
2. 跨包漂移：四包必须保持逐行等价；任何 /remember 行为差异都会立即引发多 IDE 用户的不一致报告，因此发布流程要求四包同步提交。

资料来源：packages/claude/commands/remember.md:1-1、packages/opencode/commands/remember.md:1-1

概述与设计动机

v2.9.0 重做了 /friction → /remember 记忆管线，目标是让"摩擦（friction）"不再污染热记忆（hot memory），并让抗原材料（antigens）严格来源于用户实际说过的话，而不是模型侧的代理变量。资料来源：docs/remember-README.md:1-40

热记忆是系统在工作会话中维护的、用于即时召回的近线记忆层；摩擦抗原则是在用户对模型行为表现出负面反应时，抽取出的、用于后续过滤与去敏的"反向信号"片段。两者通过统一的管线串联，形成"用户原话 → 抗原聚类 → 热记忆登记"的闭环。

管线阶段与数据流

整个管线在用户调用 /friction 时启动，最终把处理后的抗原集合交由 /remember 写入热记忆。

flowchart LR
  U[用户原话反应] --> F[/friction 收集/]
  F --> C[按内容/短语重叠聚类]
  C --> A[生成抗原 Antigens]
  A --> R[/remember 写入/]
  R --> H[(Hot Memory)]
  H -. 反哺 .-> F

• 收集阶段：仅采集用户实际表达的反应，剔除模型代理变量（如工具返回、内部状态）。资料来源：packages/claude/commands/remember/friction.js:1-80
• 聚类阶段：按内容/短语（content/phrase overlap）聚合相似反应，避免噪声扩散。资料来源：docs/antigen-gate-prd.md:1-60
• 登记阶段：通过 /remember 把过滤后的抗原写入热记忆，防止摩擦信号反过来污染主记忆。资料来源：packages/claude/commands/remember.md:1-50

跨工具包一致性

v2.9.0 的修复被"完全一致地"应用到了全部四个工具包，确保行为可预期：

资料来源：packages/opencode/command/remember.md:1-40、packages/ampcode/commands/remember.md:1-40、packages/droid/commands/remember.md:1-40

这种"一刀切"策略避免了用户在切换 IDE 助手时遭遇行为差异；同时，stash.md 仍然作为旁路通道，用于把抗原暂存到冷存储，待后续批处理。资料来源：packages/claude/commands/stash.md:1-30

精度修复与边界

本次发布的"precision fixes"主要围绕两点收紧边界：

1. 抗原来源必须可追溯到用户原话：任何来自工具日志、模型自评的"摩擦信号"都不再被允许作为种子。资料来源：docs/antigen-gate-prd.md:20-60
2. 写入热记忆前必须经过聚类去噪：单一反应不直接落库，避免偶发抱怨过拟合进 hot memory。资料来源：docs/remember-README.md:30-70

这样设计的好处是，热记忆能够更稳定地反映用户的长期偏好与反复出现的不满，而不是被单次情绪化反应带偏；副作用是 /friction 的即时反馈会略有延迟——需要聚类完成后才进入 /remember 队列。

安装器整体职责与入口

安装器以 Node.js CLI 为入口，提供 install、uninstall、status、update 等子命令，将原本散落在多个工具目录下的命令文件统一注册到目标工具的插件位置。

• CLI 解析层位于 installer/cli.js，负责参数解析、命令路由与上下文注入。
• 核心调度由 installer/installation-engine.js 承担，串起包解析、路径计算、文件复制、报告生成等阶段。
• 面向用户的指南详见 docs/INSTALLER_GUIDE.md，包含每个工具的差异点与已知限制。

flowchart LR
    A[cli.js<br/>命令入口] --> B[installation-engine.js<br/>安装引擎]
    B --> C[path-manager.js<br/>路径解析]
    B --> D[package-manager.js<br/>包注册与发现]
    B --> E[report-template.js<br/>结果报告]
    C --> F[(目标工具工作区)]
    D --> F

多工具分发机制

liteagents 通过 package 抽象来表达每一种目标工具的差异（路径布局、文件命名、是否支持子命令、是否需要元数据注入等）。package-manager.js 负责枚举和加载这些声明。

• 包注册表：在 installer/package-manager.js 中按 claude、opencode、ampcode、droid 等键值注册，每个包描述了源资产、根目录、目标目录与可选的 pre/post 钩子。
• 路径解析：installer/path-manager.js 根据当前操作系统、用户主目录与工具自身约定的目录（如 .claude/commands、~/.config/opencode/agents）动态推导目标路径，避免硬编码。
• 统一资产源：所有 commands/ 与 agents/ 资产以同一份源码分发，安装器在写入时仅做最小化的适配（如改写 frontmatter 中的工具字段），从而保证四个工具上的 /friction、/remember 等命令行为一致。这一点在 v2.9.0 的改动中尤为关键——/friction → /remember 流水线被同时应用到全部四个包，避免了工具之间的行为漂移。

资料来源：installer/package-manager.js:1-80，installer/path-manager.js:1-60

安装引擎的工作流

installation-engine.js 把整个安装过程拆成可中断、可回滚的阶段：

1. 预检（preflight）：校验 Node 版本、目标目录可写性、是否已有旧版本。
2. 资产收集：依据 package-manager 的注册表决定要复制哪些 commands/ 与 agents/ 资产。
3. 路径映射：调用 path-manager 把源路径映射到目标工具的实际位置。
4. 写入与权限设置：执行文件复制，必要时赋予可执行权限。
5. 结果汇总：把每个包的安装/卸载/跳过状态交给 report-template.js 渲染为终端可读的报告。

回滚机制由引擎内部维护的“操作栈”实现：每一步成功执行后压栈，失败时按 LIFO 顺序反向撤销已执行的操作，确保即便中途出错也不会留下半安装状态。

资料来源：installer/installation-engine.js:1-120，installer/report-template.js:1-40

扩展机制：如何新增一个工具包

扩展性的核心是把“差异”收敛到 package 描述里，而不是分散到 CLI 逻辑中。新增一个目标工具通常只需要三步：

1. 在 package-manager.js 中注册新包：声明 name、sourceRoot、targets、hooks 等字段，定义它如何消费 commands/ 和 agents/ 资产。
2. 在 path-manager.js 中补齐路径规则：如果该工具使用了非标准的安装目录，需要新增一条解析规则，让引擎在跨平台环境下都能正确定位。
3. 更新 report-template.js 的可选标签：当新工具的命名或状态文案与其他工具差异较大时，可在报告模板中补充对应的显示名称。

这种“声明式扩展”使得 v2.9.0 中的 /friction → /remember 流水线重写可以一次性应用到全部四个工具包，而不必在每个工具分支中重复修改。社区反馈中提到的“工具之间行为一致”也正是依赖这一扩展机制才能实现。

资料来源：docs/INSTALLER_GUIDE.md:1-80，installer/package-manager.js:80-140

错误处理与可观测性

安装器对失败场景提供两层信号：

• 细粒度阶段日志：引擎在每个阶段（preflight、collect、map、write、report）输出结构化日志，便于在 CI 或脚本中解析。
• 人类可读报告：report-template.js 把每个包的结果聚合成表格，包含 installed、updated、skipped、failed 四种状态以及失败原因摘要。

status 子命令则复用同一组组件做“只读扫描”，因此报告与实际状态不会出现两套数据源。

资料来源：installer/installation-engine.js:120-180，installer/report-template.js:40-90，installer/cli.js:1-60

小结

liteagents 的多工具分发层通过 cli.js → installation-engine.js → {package-manager, path-manager, report-template} 的清晰分层，把“同一份资产、不同宿主环境”这件事收敛到一组可声明、可扩展的模块中。对于希望接入新 AI 编程工具的贡献者而言，理解 package 注册表与路径解析规则是扩展的入口；对于使用者而言，理解这一分层也有助于在升级（如 v2.9.0 的 friction 流水线改造）时快速判断哪些行为变化是横跨所有工具的、哪些是某个工具特有的。

Pitfall Log / 踩坑日志

项目：hamr0/liteagents-skill-installer

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 liteagents-skill-installer 与安装入口 liteagents 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx liteagents
• 证据：identity.distribution | https://github.com/hamr0/liteagents | repo=liteagents-skill-installer; install=liteagents

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/hamr0/liteagents | host_targets=mcp_host, claude_code, claude

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/hamr0/liteagents | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/hamr0/liteagents | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/hamr0/liteagents | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/hamr0/liteagents | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/hamr0/liteagents | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/hamr0/liteagents | release_recency=unknown