Skip to content

AGENTS.md

Latest commit

 

History

History
77 lines (66 loc) · 7.44 KB

AGENTS.md

File metadata and controls

77 lines (66 loc) · 7.44 KB
Raw

AGENTS.md — TopoCode 仓库协作规则

本仓库是独立外挂式 Agent 项目实时分析系统。在这里工作的任何 AI 必须先读 docs/ARCHITECTURE.md（权威架构规范：模块地图、数据流、Schema、存储布局、扩展点）。

嗅探范围使用配置discovery_scope；前台嗅探中心通过/api/folders浏览子目录、上一级和当前目录，也保留绝对路径粘贴。 未设置时限已追踪目录。候选不得越过选定目录向上扩展；变更范围立即失效嗅探缓存，已有追踪不自动移除。 会话cwd只是启动位置，不等于项目根；有成功文件改动时优先按改动路径定位最近项目标记目录，父目录会话中的子项目因此独立候选。 同轮文件若命中多个具体项目则丢弃归因，不抢父项目；候选展示modified_file或cwd_only低置信依据和文件样例。

运行

python3 server.py --project <被观察目录> --port 8765
# 打开 http://127.0.0.1:8765

无第三方依赖：后端纯 Python 标准库，前端是单页 web/index.html。不要引入框架与包管理器。

发布与默认配置

默认models为空，首次启动为evidence_only；模型凭据仅由用户配置到自身数据目录。发布仅包含源码、文档与审核后的截图，排除会话JSONL、日志、缓存和本地运行配置。

不可违反的边界

  1. 只读观察：永不写被观察项目目录与任何 agent 家目录；状态只写 ~/.TopoCode/。
  2. HTTP 只绑 127.0.0.1。
  3. 送模型的只有脱敏摘要与文件元数据，源码正文/diff不送模型；凭据一律脱敏。 文件导读允许经/api/file_code按需向本地页面返回脱敏代码块，限登记项目内文本文件512KB、单块2000行。 校验真实路径、敏感文件与行号，源码不进入事件、memory或模型输入；未知函数边界明确显示局部预览。
  4. 模型调用失败一律降级 evidence_only，不抛穿请求线程。
  5. 不做 goal/todo/编排/调度/执行 agent —— 本项目是纯观察者。

改动守则

  • 事件幂等：以 (session_id, turn_id) 派生的稳定 event_id 为准；后到的更完整事件经 store.event_needs_update 按实际证据变化走upsert，包含结束状态、同数路径变化和短最终回复。 is_completed=False 时只展示collecting，结束后分析；成功写工具结果确认文件证据。
  • 架构写入统一走 knowledge/revision.py:revise，全量/手动/自动共用项目锁；忙时返回409。 incorporated_events 记录event_id对应证据指纹，pending按全量完成事件计算；每次最多20轮增量，后续轮询续处理。 前端ARCH_JOBS独立于DOM维护项目状态，重绘始终保留禁用状态。 组件身份是稳定 kebab-case id，name 只作展示；依赖、选中、图谱节点按 id 寻址。 旧档案加载时补 id；全量重生按文件重叠继承 id；增量按 id 匹配并允许改名。
  • 选文提问走knowledge/explanations.py与/api/knowledge/explain，说明文本纯文本展示，取消自动分词和下划线。 鼠标选中最多2000字后仅显示鼠标旁的小提问按钮，点击才打开大弹窗并检索本地；点击外部、滚动或Esc关闭小按钮。 本地检索优先精确记录，其次长度至少12字、字符序列相似度≥85%的记录。 缓存查询无须等待生成锁；面板保留一个可选问题输入和生成按钮，参考资料折叠；检索15秒、生成90秒前端超时，状态区分并提供错误重试。 相似记录标注原选文且仅展示通用部分；用户明确点击提问/重新提问才调用模型，词库/面经保留参考。 通用释义跨项目缓存，项目作用按真实项目/语言/上下文指纹隔离；本地缓存优先，跨项目仅自动展示通用部分。 分支复制原分析messages并追加问题，父会话不变；同供应商/模型前缀复用只是缓存命中条件，usage才是命中证据。 统一模型请求携带x-opencode-session，以脱敏首条message的blake2b派生稳定标识，原分析与选文分支共享路由标识。 自身data目录的explanations/{branches,general,projects}原子写+锁；源码和凭据不进入分支上下文。
  • 新增知识词条 → 对应领域 knowledge/bank_ext_<domain>.py（schema 见 ARCHITECTURE.md §4.3）， id 全局唯一，改完跑导入断言验证；前后端共用规范化词表，新增问答附开源参考链接并标注整理题。
  • 架构输入选择统一走 snapshot/selection.py：关键角色交替、同类目录轮转；超预算时 关键阶段最多60%、目录覆盖最多20%，剩余按依赖排序补齐，避免单类文件挤占全部名额。 8000快照/600分析预算的遗漏及stage_counts通过coverage显式报告。
  • 新增平台 → 实现 platforms/base.py 接口并注册；伪路径过滤在适配器层完成。
  • 左侧会话卡片内部仍用session_id分组/去重/取消追踪，前台不展示编号；标题取该会话首句用户提问的压缩预览，时间紧邻标题显示，真实时间来自首轮occurred_at。
  • 前端改动在 web/index.html 内完成，中英双语文案都要加在 I18N 字典里。 视觉采用石墨底色、蓝色主操作和统一深色架构画布；样式复用根变量，正文14px，更新现有规则而非继续叠加主题覆盖。
  • 架构图展示契约见 docs/ARCHITECTURE.md §4.2.1：项目容器内嵌子系统与功能块， 入口在上、核心居中、协作模块两侧、基础模块在下；真实依赖连线与模块详情独立维护。 蓝图卡片与选中状态使用组件 id，界面仍显示 name。
  • 右侧仅架构图与文件树两个视图，文件树使用graph/navigation.py的完整有界快照路径， 展开状态按项目保存，关系是双向导入，文件点击打开导读而非仅过滤会话。 导读/代码块前端URL缓存64项、10秒并合并在途请求；过期重取，旧响应按序号隔离。后端导读缓存32项、5秒，文件mtime_ns/size提前失效；源码块只存浏览器内存。
  • 文件导读用snapshot/guide.py提取启动块、限定符号名、行号区间与调用引用；模型reading_steps 限定给定符号，元数据/文档事实与推断分开展示，文件模型输入使用摘要与符号，保持源码正文不外发。
  • 会话模型使用 dialogue.v4：同次调用生成change_summary具体修改描述与technical_meaning改动含义。 监听、会话分析、架构增量修订由独立有界后台队列处理；事件先落盘并推送evidence，分析完成后按原event_id回写。首次采集只选项目最近5个完成轮次，此后新增轮次持续分析；analysis-scope文件持久化历史基线与分析资格。回补接口recent_rounds选择最近N轮加入，队列满后轮询补排，按证据指纹和模型标识去重。 前台常驻显示修改描述、完整改动路径和含义，路径打开文件导读，其余证据默认折叠；所有改动路径保留展示。 历史缺少修改描述时展示已捕获文件数/待分析状态。历史会话知识字段保留存储但不展示；画像留在 UserMemory。 架构词典、文件导读和全局知识库独立保留；详见 docs/ARCHITECTURE.md §4.1。
  • 历史上下文注入模型必须经过 SessionMemory.build_context_summary(token_budget=...)， 不得绕开 token 预算压缩直接拼接。
  • 改了本文档或 docs/ARCHITECTURE.md 描述的行为，同步更新对应文档。