以 AI 会话探索与被动知识雷达为双重输入，以证据和实验持续校验，构建可由个人积累、团队共享的技术知识调研与沉淀的图谱。
Agent Tech Radar 将“人因为具体问题而发起的 AI 会话”与“系统不等人提问便持续运行的知识雷达”汇入同一套知识流程。它不只收藏资料，而是继续查源、实验、复盘和审核，最终将技术认知变成可追溯、可修正、可共享的决策资产。
当前版本：v1.1.0 · Seed / 种子项目。 当前是可运行 Demo，用来固化这套双输入思想、验证核心交互和建立可追溯的数据边界；它还不是完整的自动化研究平台，也不宣称已经解决了“全网无遗漏”。
v1.1 把图谱从“节点摘要集合”推进为一份可交互的立体文档目录：完整研究文档承载知识，章节、技术、能力、证据和实验负责导航与校验。仓库内置“欧洲法律 Agent：框架与可靠性”公开专题，克隆后即可复现下面的本地示例。
共享全景与专题图谱可以并存。文档与重点章节构成主骨架，技术和能力节点提供跨章节语义连接；标签使用大字号、加粗、描边和框内换行，并随大屏空间响应式放大。
在文档或章节节点停留约 0.45 秒，左侧阅读器自动打开完整正文并定位对应章节，右侧仍保留图谱语境；正文可以独立滚动，也能直接进入 Codex 继续研究。
Markdown 中的 Mermaid 代码块会在独立文档页和图谱阅读器中渲染为本地 SVG，同时保留可折叠源码和失败回退，避免把流程图降级成难读的 TD 源码。
用户通过 Codex 或其他 AI 会话提出问题、挑战结论、比较方案和修正理解。默认沉淀物不是一批只有标题的短节点，而是一篇可阅读、可修订、可持续查证的研究文档。文档保留完整论证和适用边界，同时记录形成认识时的关键问答锚点与回到原任务的入口。
雷达通过有边界的 API、包注册表、Release Feed、官方组织列表和论文索引，发现没见过的技术、新版本和可能影响已有判断的变化。它记录查询族、技术类别、去重结果、排除原因和搜索空白，使广度可审计。
AI 会话和雷达候选都只是调研起点。重要外部断言需要回到官方文档、官方仓库、标准、论文、发布记录或可重复实验；冲突证据被保留，不确定性被明示。
候选、研究文档、未归档认知片段、待查证假设、外部证据、实验结果和正式结论分层保存。AI 可以提出更新，但不能静默将线索升级为事实；人通过接受、修改或驳回提案掌握最终知识权。
系统不再把所有知识挤在唯一一张图上，而是保留团队共享的技术全景，同时按研究问题建立个人或团队专题图谱。图上的文档和重点章节是立体目录，相关技术、能力、结论、证据和实验作为语义桥梁补入；私人文档不会因此自动进入共享全景。
知识图谱不是为了堆满节点，而是让人先看见技术路线和当前认知边界，再从节点进入 Codex 继续追问、查源和实验。节点大小只表达规模与活跃信号，不代表技术质量。
发现层通过多个技术类别、生态和查询族反复交叉搜索，并保留已排除项目与原因。它衡量的是搜索过程是否可审计，不把有限来源包装成“已经搜全”。
采集层只保存版本、时间、URL 和内容哈希等确定信号；去重后的变化才交给 Codex 阅读和判断是否影响已有结论。版本变了是事实，但不自动等于技术选型应该改变。
开发 AI Agent 系统时，技术选型很容易被“我已经知道的几个框架”限制。新项目、新范式和新版本持续出现，一次性调研报告很快就会过期。
这个项目尝试建立一个可持续的技术知识回路：
- AI 会话捕捉人主动提出的问题、质疑和认知修正，并沉淀为持续修订的研究文档。
- 被动知识雷达持续发现人尚未提问的技术、变化和类别空白。
- 两条输入流的重要断言统一通过一手证据、交叉查源和最小实验持续校验。
- 变化、证据缺口和冲突进入待审核队列，而不是由 AI 静默修改正式结论。
- 最终结果沉淀为可由个人积累、团队共享的技术知识图谱，使“已知什么、为什么相信、还缺什么”可见。
- AI 会话是认知来源，不是事实证据。 会话可以证明“这条认识如何形成”，不能单独证明外部技术断言为真。
- 两条输入流缺一不可。 AI 会话承载人的主动探索，被动知识雷达补足人尚未想到的技术范围和持续变化。
- 广度是可审计的搜索策略，不是虚假的“全部覆盖”。 系统保存查询族、技术类别、来源状态、排除原因和历次发现结果。
- 人掌握知识升级权。 候选、文档中的待查证断言、假设和正式结论分层保存，重要变更需要显式审核。
- 热度只是视觉信号。 节点大小可反映 Star、Fork 和活跃度，但不等于技术质量或适配度。
- 实验应尽量能证伪结论。 保存假设、依赖、模型、输入、随机种子、指标、原始日志和结果。
- 图谱是导航地图，不是信息垃圾场。 默认展示少量高价值节点，证据、实验和正式结论按需展开。
更完整的产品约束见 产品原则。
- 总览仪表盘、知识图谱、变化信息流、发现候选、实验和审核页面。
- 研究文档列表与长文阅读页：包含完整目录、正文、会话来源、相关技术和从指定章节进入 Codex 的入口。
- 研究文档中的 Mermaid 代码块会在正文和图谱悬停阅读器中渲染为本地 SVG 流程图；源码默认折叠保留，渲染失败时可回退检查。
- 支持多张技术图谱：在“Agent 技术全景”与按问题划分的专题图谱之间切换。
- 专题图谱以文档为中心，展开重点章节，再引入相关技术、能力、结论、证据和实验作为连接上下文。
- 章节节点支持延迟悬停阅读：停留约 0.45 秒后在左侧打开完整文档，自动定位所选章节，并可用滚轮独立翻阅；同一文档在当前页面内只加载一次。
- 图谱使用加粗、描边和框内自动换行的高可读标签；节点高度、字号、尺寸和画布高度会随内容与可用空间自动增长，自然布局还会按画布宽高比铺开。
- 主流技术节点根据规模与活跃信号相对放大，冷门节点更小。
- 认知片段支持新增、查看、编辑、归档、恢复和关系维护，用于保留尚未合理纳入长文档的疑问、质疑、纠正和定位锚点。
- AI 会话探索当前以 Codex 为首个集成：可显式导入任务链接或任务 ID，把一段会话沉淀为一篇长期研究文档，并保留具体 turn/item 的问答锚点。
- 每个锚点可以回到原 Codex 任务并复制定位句，也可以带着该片段创建新任务继续追问；当前官方尚无稳定的消息级深链，因此先用“打开任务 + 会话内搜索”定位。
- 会话导入文档、真实任务 ID 和原始片段默认仅本机保存；团队共享前需要另行整理为不含私人内容的可共享文档。
- 被动知识雷达当前有边界地使用 GitHub Repository/Releases API 和 PyPI JSON API，进行广度发现、版本变化和热度信号收集。
- Git/YAML 保存人可审查的源数据，SQLite 只是可重建查询索引。
- 仓库包含“欧洲法律 Agent：框架与可靠性”公开示例文档与专题图谱，方便直接验证文档优先、章节导航、悬停阅读和 Mermaid 渲染。
- 不会静默读取私人 AI 会话；导入和同步需要用户显式发起。
- 还没有实现所有计划来源，例如 npm Registry、arXiv API 和官方组织观察表。
- 还没有长期调研任务队列、失败恢复、成本预算和自动化评测闭环。
- 还没有建立可用于生产系统的权限、多用户、部署和安全隔离。
flowchart LR
Conversation["AI 会话探索\n问题・回答・质疑・修正"] --> Documents["持续修订的研究文档\n保留会话来源"]
Discovery["被动知识雷达\nAPI・Registry・Feed"] --> Candidates["待评估候选"]
Documents --> Gaps["证据缺口 / 追问"]
Candidates --> Gaps
Gaps --> Research["AI 研究执行器\n查源・实验・交叉验证"]
Research --> Proposals["待审核提案"]
Proposals -->|"人工接受 / 修改 / 驳回"| Knowledge["正式结论与决策"]
Knowledge --> Graph["立体目录图谱"]
Documents --> Graph
Candidates --> Graph
Graph --> Gaps
需要已安装 Conda（Anaconda、Miniconda 或 Miniforge 都可以）。
git clone <your-repository-url>
cd agent-tech-radar
./scripts/create_env.sh
conda run -n agent-radar uvicorn app.main:app --host 127.0.0.1 --port 8765macOS 也可以双击 启动Demo.command。
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.lock.txt
uvicorn app.main:app --host 127.0.0.1 --port 8765python -m radar.cli index
python -m radar.cli collect
python -m radar.cli discover --per-query 25
python experiments/source_coverage/run.py
pytestcollect 和 discover 只调用明确的 API，不内置通用爬虫。未设置 GITHUB_TOKEN 时仍可调用 GitHub 公开 API，但受到更严格的频率限制；如果需要提高频率，请在本地环境变量中配置 Token，不要写入仓库。
| 目录 | 含义 |
|---|---|
knowledge/conversations/ |
用户显式导入的 Codex 会话来源，默认不进入公开 Git 提交 |
knowledge/conversations/anchors/ |
具体 turn/item、原始片段和定位短句，仅本机保存 |
knowledge/documents/ |
可共享的长文研究文档及元数据，是默认知识主体 |
knowledge/documents/private/ |
从私人会话沉淀的本机文档，默认不进入 Git |
knowledge/nodes/ |
尚未归档进文档的可共享认知片段 |
knowledge/nodes/private/ |
从私人会话导入的本机认知片段，默认不进入 Git |
knowledge/maps/ |
可共享的技术全景与专题图谱定义 |
knowledge/maps/private/ |
包含私人会话选择范围的本机专题图谱，默认不进入 Git |
knowledge/claims/ |
经过审核的正式技术结论 |
knowledge/evidence/ |
独立于会话的外部证据索引 |
proposals/ |
AI 研究执行器提出、等待人审核的知识变更 |
inbox/ |
确定性采集器发现的变化和未审核候选 |
discovery/ |
技术类别、来源组合和广度查询族 |
experiments/ |
可重复实验的定义、代码、日志和结果 |
.radar/ |
可从 YAML 重建的本地 SQLite 索引和运行状态，不提交 Git |
这是一个 local-first 种子项目，团队共享能力仍处于设计与迭代阶段。它尚不提供生产级身份验证，也不应直接暴露在公网。会话 ID、私人笔记、本地路径和 API 凭据都可能是敏感信息。详见 安全说明。
当前种子仓库尚未选择开源许可证。在明确添加 LICENSE 之前，请不要假定获得了复制、修改或再分发权。前端固定依赖的许可信息见 THIRD_PARTY_NOTICES.md。