agent-pulse

Agent Pulse

将 Agent Pulse 作为有证据支撑的情报系统来运行，而不是新闻聚合器。明确区分事实、 证据、背景、影响、判断和后续信号；每项公开声明都必须可追溯至允许使用的来源证据。

何时使用此技能

• 用户希望在本地运行 Agent Pulse、刷新其仓库快照，或查看 Control Room 和公开网站。
• 用户需要添加、分类、测试、启用、降级、隔离或停用数据源。
• 用户要求收集信号、去重或聚类 Event、审计来源健康状况，或评估系统能力。
• 用户希望撰写叙述、每周简报、Scout 机会，或生成保护隐私的静态导出。
• 用户正在更改采集器、架构、排名、发布门槛、来源生命周期或公开 DTO。
• 任务涉及 Agent Pulse 本身，而非通用网页抓取或一般研究。

说明

步骤 1：记录工作任务包

记录所需结果、受影响的层面、证据边界和验证目标：

• 结果：运行、调查、更改代码/架构、刷新数据、发布或研究。
• 层面：仅服务端的 Control Room/数据库、采集流水线，或公开静态导出。
• 对象：Source、SourceRun、Signal、Event、Track、Actor、Resource、View、Job 或 Scout 机会。
• 证据：主要 URL 或论文、来源等级、溯源信息、时效性和不确定性。
• 范围：单个来源、符合条件的批次、所有来源、一篇叙述或一次发布。
• 验证：专项测试、npm run check、导出验证、隐私扫描或浏览器冒烟测试。

如果请求含糊，不要擅自做出发布决定。询问缺少的目标，或将项目保留在审核/草稿状态，并说明阻塞原因。

步骤 2：编辑前先阅读项目约定

在 Agent Pulse 仓库根目录中，先阅读 AGENTS.md 和相关文档/规范。对于采集/发布工作， 至少查阅 docs/ARCHITECTURE.md、docs/SOURCES.md 和 docs/LEGAL.md。 遵循现有模块边界，不要为特定来源另设例外：

• src/collectors/ 负责 SourceAdapter 契约、抓取安全和适配器。
• src/domain/ 负责纯 URL、聚类和评分规则。
• src/db/ 负责 Kysely 架构、迁移、仓库和种子目录。
• src/pipeline/ 负责采集、聚类、评估、Scout 和导出编排。
• src/server/ 负责公开/管理 API 和安全标头。
• web/public/ 是无框架的静态情报网站；web/admin/ 为私有区域。
• tests/ 存放单元测试和 SQLite 集成测试。

对于架构、来源生命周期、排名、发布或 Scout 相关更改，应先更新对应规范，并同步更新代码、测试和面向用户的变更日志。

Step 3：选择范围最小的操作路径

使用现有的 npm 脚本，并将相互独立的操作分开：

需求	起始命令	防护措施
安装／启动本地应用	npm install; cp .env.example .env; npm run dev	切勿提交 .env 或凭据
为本地 SQLite 填充初始数据／迁移	npm run db:seed 或 npm run db:migrate	保留较新的本地证据
收集并聚类	npm run collect	默认仅收集合格来源；隔离失败
限定收集范围	npm run collect -- --scope=eligible 或 --scope=all	对单个来源使用 --source=<id>；仅在有意为之时使用 --backfill
来源健康状况	npm run sources:audit	不具破坏性；记录降级／失败／跳过的证据
系统能力	npm run evaluate:system	检查回归时与基线进行比较
运维对账	npm run ops:reconcile	不要悄然更改架构／排名规则
Scout 假设	npm run scout:generate -- 3	限制为 1–18；Scout 不能作为事实发布
静态发布	npm run export 然后 npm run public:validate	仅导出列入允许列表的已发布 DTO
合并／发布验证	npm run check	必须包含 lint、类型检查、测试、导出和公开验证

进行代码更改时，先运行范围最小的针对性测试或命令，然后在声称完成前运行 npm run check。刷新数据时，记录刷新前后的计数、来源运行状态，以及输出产物或报告路径。

Step 4：严格遵守证据和来源边界

• 优先使用官方 API、RSS/Atom、GitHub Releases、论文、申报文件及其他稳定的公开来源。
• Tier 1 是一手事实；Tier 2 是专业核实；Tier 3 是专家解读；Tier 4 是传播热度。聚合器用于发现／感知热度，绝不能作为唯一事实证据。
• 将置信度（事实正确性）与热度（传播范围）分开。不要把手动输入的分数当作测得的传播范围。
• 公开事件需要提供可点击的原始来源，并且通常需要一个 Tier 1 来源或两个相互独立的 Tier 2 来源。例外情况须标记为未经核实。
• 遵守 robots 规则、许可证、条款、速率限制、缓存和来源配额。不得绕过登录、WAF、CAPTCHA、付费墙或平台限制。若浏览器抓取是实际任务，则交由 scrapling 处理。
• 限定超时、重试、退避、重定向、响应大小和并发数。重新检查重定向目标以防止 SSRF，并拒绝回环、链路本地、私有、包含凭据或容易受到 DNS 重绑定攻击的 URL。
• 存储溯源信息和有界元数据，而非完整的第三方文章。来源退役后仍须保留历史溯源信息。

Step 5：明确设置发布和隐私关卡

自动收集的对象只有在满足所有确定性关卡后才能进入 review。将事实与解读分开，并标注不确定性。LLM 增强可以起草洞察，但必须能追溯到证据，且不得绕过架构、证据、就绪状态、冲突或发布关卡。

导出前，确认公开输出仅包含列入允许列表的 DTO，且不含数据库、令牌、凭据、原始载荷、代理设置、本地路径、管理字段或私人备注。进程成功退出并不构成证明：请引用验证输出、生成的产物或测试结果。

Step 6：以可审计的交接报告结果

返回一份简明报告，包含：

1. 请求的操作路径和范围；
2. 更改的文件、来源或命令；
3. 证据和溯源状态；
4. 相关情况下的前后计数／状态；
5. 验证命令和实际结果；
6. 剩余的不确定性、降级来源、未通过的关卡以及下一个信号。

绝不能将经过整理的种子／演示数据集称为生产级持续检测，也绝不能将实验性或计划中的能力描述为已发布。

示例

示例 1：刷新符合条件的来源

运行 npm run collect -- --scope=eligible，检查 JSON 采集／聚类结果，并分别报告来源故障以及已创建、已关联或已推迟的事件。不要仅因采集成功就将待审核事件提升状态。

示例 2：添加新的来源适配器

阅读来源和法律规范，扩展 SourceAdapter 边界，添加能力元数据、夹具覆盖、成功／失败／降级测试，以及生命周期／来源信息处理。运行针对性的契约测试，然后运行 npm run check；在新来源通过真实观察窗口和合规检查之前，将其保留在 draft 或 shadow 状态。

示例 3：发布 Scout 机会

只有在确认触发事件和证据后，才运行有界 Scout 命令。将结果明确标记为假设，并说明目标用户、时机原因、非共识洞察、首个小型实验、风险和失效条件——不要将其表述为事实、投资结论或外部行动。

示例 4：验证公开发布

先运行 npm run export，再运行 npm run public:validate，并检查生成的公开指纹或报告。确认不存在私有控制平面数据，并在报告发布已就绪之前，为每个重要事件关联公开证据。

最佳实践

1. 优先采用现有契约和可轻松回退的小幅差异，而不是针对特定来源走捷径。
2. 在每份报告中区分已编入目录、已观察、活跃和已发布状态。
3. 将来源故障视为独立的健康状态，不要因此丢弃整个批次。
4. 本地默认行为使用 SQLite；没有真实集成覆盖时，不要声称支持 MySQL。
5. 对用户可见的更改，确保变更日志与公开产品变更日志数据保持同步。
6. 保留原始证据边界，绝不将私有运营数据放入 GitHub Pages。
7. 记录哪些因素会强化、削弱或推翻每项长期判断。

参考资料

• Agent Pulse 仓库
• 架构与数据流
• 数据来源、层级与采集政策
• 负责任使用与法律边界
• 能力映射
• 本地命令与边界矩阵