extract-agent-0.4.1-released

Changelog

本文档记录项目的主要修改。

2026-04-27

重构 — DocJSON 自动识别与 xdev ToolHub 注入

• 版本号切换到 0.4.0
• 新增 DocJSON adapter，自动识别 canonical tree.root 与 PPX pages[].objects[]
• PPX DocJSON 会按 Markdown 标题层级还原 title -> section 文档树
• Document.from_dict()、create_input() 和 DocJSON 执行 API 会防御性 normalize
• DocJSON 执行进入 Document-only：flat/article/config 旧路径改为清晰失败
• code_executor 支持显式 tool_hub=，但不自动读取 xdev 配置
• xdev run / xdev eval / Python API 会自动读取 xdev 配置、构造单个 ToolHub 并注入 extract(document, tool_hub)
• workspace 模板、prompt、skill 和主要文档改为推荐显式 ToolHub 注入写法
• console scripts 收敛为 tree-sitter-cli、xdev、xdev-config、agentic-extract、pdf-ai-explorer
• 移除 pyproject.toml 中的私有依赖解析 index，pdf-ai-explorer 改为仓库本地 wheel source

2026-04-24

修复 — DeepSeek thinking/tool-call 兼容

• agentic-extract 现支持显式 deepseek/<model_name> 前缀
• 官方 DeepSeek OpenAI 兼容端点会自动切换到 DeepSeekMultiAgentFormatter
• 避免在 DeepSeek chat.completions 路径上把 thinking 降级成普通文本，从而保留 reasoning_content
• 新增 test_model_factory.py 回归测试，覆盖 formatter 选择和 preserve_thinking 保护逻辑

修复 — structured output 探测兼容 DeepSeek JSON 模式

• probe_structured_output() 的探测 prompt 改为显式包含 json
• 避免 DeepSeek 因 response_format={"type":"json_object"} 且 prompt 未提及 json 而误报 probe 失败
• 新增对应 supervisor 回归测试

改进 — DeepSeek 默认配置与文档示例

• 工作区与全局 agentic-extract 配置中的标注模型默认切到 deepseek-v4-flash
• xdev / 提取链路相关示例统一改为 deepseek-v4-flash
• 主 agentic-extract 模型仍保留 deepseek-v4-pro 的推荐搭配

2026-04-23

新增 — agentic-extract 运行事件落盘与详细 agent 消息

• 默认将运行事件写入 workspace/.agent_state/events.jsonl
• RunRecorder 的阶段、迭代、step、heartbeat、完成/失败事件会落成 JSONL
• 基于 AgentScope hook 增加详细 agent 事件：agent_call_started、agent_message、agent_call_completed
• agentic-extract auto 路径补充 setup / prepare 相关事件，避免事件流只覆盖 run 主循环
• 新增 events.py 事件写入模块与配套测试，tests/agentic_extract 全量通过

新增 — 维护者 release-process skill

• 新增仓库本地 skill：docs/skills/release-process/
• 新增随包发布版 skill：src/agentic_extract/skills/release_process/SKILL.md
• README.md 与 docs/release_process.md 现在直接指向 release-process skill
• xdev export-skills 新增导出 release_process/SKILL.md

2026-04-20

改进 — agentic-extract CLI 预算控制与文档整理

• agentic-extract 默认预算改为 standard：max_iterations=10、agent_max_iters=25
• 新增 --budget fast：max_iterations=10、agent_max_iters=10
• 新增 --budget full：max_iterations=50、agent_max_iters=100
• 支持继续通过 --max-iterations、--agent-max-iters、--supervisor-max-iters、--business-max-iters、--dev-max-iters 显式覆盖预算
• CLI 启动时会输出预算摘要，方便确认本次运行的生效预算
• Supervisor 默认模式切换为 simple
• 新增聚焦 run / auto / budget 的 CLI 文档：docs/agentic_extract_cli.md

新增 — xdev-config 全局配置向导

• 新增独立命令 xdev-config
• 支持交互式、非交互式、混合补全和 --show 查看模式
• 同时写入 ~/.config/agentic-extract/config.json 与 ~/.config/xdev/config.json
• xdev 的 extract_tool 和 llm_select_tool 会同步使用同一套 extract-llm
• 新增 CLI 测试，覆盖打码展示、必填校验、增量更新与交互补全

改进 — PDF 解析默认使用 PPX CLI

• 默认 PDF → DocJSON 路径改为调用本机 ppx parse，不再依赖 memect_api_base
• 批量 PDF 解析统一走 ppx parse <dir> --workers N，新增 pdf_parse_concurrent / XDEV_PDF_PARSE_CONCURRENT 控制文件级并发，默认 1
• PPX 输出写入临时目录，xdev 只保存最终 .xdev/data/docjson/*.json 与 .xdev/data/pdf/*.pdf

改进 — xdev run 支持直接运行单个 PDF / DocJSON

• xdev run 新增 --pdf 与 --docjson 选项
• 现在支持三种单次提取输入：doc_id、单个 PDF、单个 DocJSON
• doc_id / --pdf / --docjson 三者必须且只能选一个
• 单个 PDF 会先通过本机 ppx parse 解析成 DocJSON，再复用现有 workspace 执行链

改进 — xdev 默认提取长度与配置展示

• extract_tool 与 llm_select_tool 的默认 max_content_length 统一为 50000
• xdev-config 的 --show 和写入前 summary 现在会展示 base_url、concurrent、pdf_parse_concurrent、memect_api_base、max_content_length，并补充 llm_select_max_content_length
• xdev-config 写入 ~/.config/xdev/config.json 时，如果缺少这些默认字段，会自动补齐 base_url、concurrent、pdf_parse_concurrent、memect_api_base、extract_tool.max_content_length 与 llm_select_tool.max_content_length

改进 — extract-agent 直接暴露 pdf-ai-explorer CLI

• pyproject.toml 的 project.scripts 新增 pdf-ai-explorer = "pdf_ai_explorer.cli:app"
• 现在安装 extract-agent 时，会一并暴露 pdf-ai-explorer 命令，减少二次安装步骤
• 更新安装文档，默认安装路径改为只安装 extract-agent

2026-04-15

重构 — agentic-extract 公共 Python API、运行期事件与状态落盘

• 新增低层 pure run API：run_agentic_extract() / run_agentic_extract_async()
• 新增高层 one-click API：run_agentic_extract_auto() / run_agentic_extract_auto_async()
• 新增公共类型：RunResult、IterationResult、ProgressEvent、TokenUsage、PrepareSpec
• 新增 callback 形式的稳定粗粒度进度事件与 heartbeat，运行中可持续接收 phase / iteration / step / heartbeat 进度
• 新增运行期 recorder 与 token usage 聚合，结果中可获得 iteration_count、每轮迭代时长、总迭代时长、总运行时长，以及 cache / reasoning token 明细
• CLI agentic-extract run 已切换为低层 pure run 适配层
• CLI 新增 agentic-extract auto，负责 bootstrap + run
• RunRequest / run_agentic_extract_request*() 已标记为兼容层，不再推荐给新调用方
• state.py 的迭代记录已扩展为结构化字段：started_at、finished_at、duration_sec、token_usage、summary、error
• 删除旧入口 src/agentic_extract/loop.py
• 新增并更新测试：test_api.py、test_runtime.py、test_usage.py、test_runner.py、test_cli.py、test_state.py
• 新增当前使用文档：agentic_extract_guide.md

2026-04-14

修复 — xdev eval 评估结果属性透传

• 修复 xdev.evaluation_result.EvaluationResult 未透传底层评估对象属性的问题
• xdev eval 现在可以正常访问 overall_accuracy、total_records、field_stats 等属性并打印完整评估报告
• 为 run_evaluation() 补充集成测试，覆盖 field_stats 和 total_records 的兼容访问

删除 extract_dev 和 llm_standard_generator，迁移功能到 xdev

删除模块：

• extract_dev/ - 旧评估模块，功能已迁移到 xdev
• llm_standard_generator/ - 未使用的 LLM 标准生成模块

新增 xdev 功能：

• xdev/extract.py：extract_from_docjson 支持 workspace/program/config 三种模式
• xdev/evaluation_result.py：EvaluationResult 替代 EvaluationResultWithMetadata
• xdev/html_report.py：HTML 报告生成（PDF 链接从 manifest 读取，无则留空）
• xdev/evaluation.py：run_evaluation 返回 EvaluationResult

版本：0.2.1 → 0.3.0

2026-04-07

重构 — 删除冗余模块并清理依赖

删除模块：

• agentscope_agent/ - 已被 agentic_extract 完全替代，删除全部 44 个文件
• fact_extract/ - 未使用的事实提取 pipeline，删除全部 28 个文件
• simple_workflow/ - 未使用的工作流模块，删除全部 28 个文件

依赖清理：
从 pyproject.toml 移除 14 个未使用的依赖：

• Web 框架：fastapi, uvicorn, websockets, python-multipart
• 数据库：sqlalchemy, alembic, psycopg2-binary
• 任务队列：celery, flower, redis
• 其他：openpyxl, fact-analyze, pysbd

Bug 修复：

• 修复 scripts/agentic_batch.sh 中的 API 认证冲突问题：在子进程中 unset ANTHROPIC_* 环境变量，避免与 .agentic-extract.json 配置文件中的 api_key 冲突

影响：

• 代码量减少：删除 25,705 行，新增 2,267 行（主要是 uv.lock 更新）
• 包体积减少：wheel 从 2.2MB 降至 1.9MB
• 核心模块 agentic_extract 功能不受影响，所有测试通过

2026-04-02

改进 — agentic-extract BusinessAgent prompt 重写 + 异常处理 + Supervisor simple 模式

• BusinessAgent prompt 重写：新增"每次回复必须包含工具调用"强制规则，明确 business_guide.md 和标注文件的位置与写入方式（含 write_text_file 示例），禁止读取 program.py/tests/（DevAgent 职责），禁止写 python 脚本解析 docjson
• Agent 异常处理：BusinessAgent 和 DevAgent 调用增加 try/except，异常时打印错误信息并继续循环，避免静默中断
• Supervisor simple 模式：新增 --supervisor simple CLI 选项，Supervisor 不注册任何工具，仅做纯决策路由；适用于 reasoning 模型（如 gpt-5.4）避免 think 模式下工具调用不稳定
• Supervisor task 描述优化：task 改为直接指令形式（"运行 xdev doc 查看文档，创建 business_guide.md"），禁止使用"请业务侧提供…"等间接表达
• Agent 状态目录迁移：agent memory 从 logs/agent_memory/ 迁移至 .agent_state/，避免与运行日志混淆
• xdev doc 长文档提示优化：pdf-ai-explorer 命令示例补全（outline/search/read/content），修正参数顺序
• xdev SKILL.md 精简：移除 --data-dir 全局选项描述（workspace 内工作时无需指定）

2026-03-20

改进 — agentic-extract supervisor loop 优化

解决 Agent 不查看真实文档、不校验字段名、评估信息丢失、无停滞检测等问题：

• 评估结果结构化：_run_xdev_eval 解析完整 xdev eval 报告（字段级准确率、错误文档 ID、字段平均），EvaluationSnapshot 新增 field_average、error_count、error_doc_ids、field_accuracies、report_text 字段
• evaluate action 反馈增强：Supervisor 收到字段级准确率 + ⚠ 标记 + 错误文档列表，而非仅 "准确率 X%"
• 停滞检测：连续 call_dev 未评估计数器，3 轮建议评估，6 轮强制提醒
• Schema 字段注入：每次 call_dev 实时读取当前 schema 字段名注入 task（schema 可能被 BusinessAgent 更新）
• 首轮 workspace 状态注入：第 1 轮 Supervisor 消息包含 schema 字段、文档数、标注数、program.py 存在性
• Supervisor prompt 增强：新增首轮要求（先了解数据再决策）、task 内容规范（包含具体字段/文档ID）、停滞提醒说明
• 迭代摘要增强：get_recent_summary 从 3 轮扩展到 5 轮，追加准确率趋势

改进 — agentic-extract supervisor 决策增强

• Supervisor 决策解析重构：支持单行 JSON、markdown 代码块、多行 JSON 三种格式
• 新增 structured output 探测：启动时自动测试模型是否支持 structured output（_probe_structured_output），可用时优先使用
• 决策重试机制：文本解析失败后自动发送格式提示并重试（最多 2 次）
• SupervisorDecision 改用 Literal 类型约束 action 取值，模糊匹配纠正大小写
• Supervisor prompt 精简：两阶段工作流（调查→决策）+ 格式提醒追加到 system prompt
• Business/Dev Agent prompt 新增「工作方式」指引（读取→修改→验证，避免重复读文件）
• 新增 --preserve-thinking 选项：ThinkingToTextWrapper 将 thinking blocks 转为 text blocks，防止 extended thinking 模型循环
• 新增依赖：fact-analyze（本地 editable 包）

新增 — fact-extract analyze pipeline

• 新增 analyze CLI 命令：委托 fact_analyze 包，执行实体→事件→关系→时间线全流程
• 新增 document.py：输入适配器，PDF/docjson/纯文本 → document.json 格式
• 新增 entity_identify.py：实体识别+消歧 → entities.json
• 新增 entity_attributes.py：实体属性提取 → entity_attributes.json
• 新增 entity_relations.py：段落级实体关系提取 → entity_relations.json
• 新增 event_extract.py：事件提取 → events.json
• 新增 event_relations.py：事件关系发现 → event_relations.json
• 新增 timeline.py：纯规则时间线合成 → timeline.json
• 新增 _batch.py：共享的按字数切分 batch 工具
• auto_section.py 新增 system_prompt 和 intermediate_dir 参数

2026-03-16

改进 — fact-extract section-mode 与默认后端调整

• --auto-section 标志替换为 --section-mode 选项，支持三种模式：
  • docjson（默认）：按原始 section 节点合并文本
  • line：每个 textline 作为独立 evidence item
  • auto：LLM 自动分段（等同原 --auto-section）
• evidence.py 中 extract_evidence_items() 新增 section_mode 参数，重构为统一分发逻辑
• 新增 _split_section_lines() 函数，支持行级粒度的 evidence 拆分
• 默认 extractor-backend 从 agentic 改为 llm-once（extract-task/run-workers/run 三处）
• 删除 src/fact_extract/SKILL.md（已迁移到本地 skills 目录）

改进 — tiktoken 离线缓存迁移到公共模块

• 将 tiktoken 缓存文件从 agentscope_agent/data/ 迁移到 extract_agent_common/data/tiktoken/
• 新增 extract_agent_common/tiktoken_cache.py：ensure_tiktoken_cache() 使用 importlib.resources 定位缓存目录
• agentic_extract/cli.py 和 agentscope_agent/cli.py 统一调用此...

extract-agent-0.4.0-released

Changelog

本文档记录项目的主要修改。

2026-04-27

重构 — DocJSON 自动识别与 xdev ToolHub 注入

• 版本号切换到 0.4.0
• 新增 DocJSON adapter，自动识别 canonical tree.root 与 PPX pages[].objects[]
• PPX DocJSON 会按 Markdown 标题层级还原 title -> section 文档树
• Document.from_dict()、create_input() 和 DocJSON 执行 API 会防御性 normalize
• DocJSON 执行进入 Document-only：flat/article/config 旧路径改为清晰失败
• code_executor 支持显式 tool_hub=，但不自动读取 xdev 配置
• xdev run / xdev eval / Python API 会自动读取 xdev 配置、构造单个 ToolHub 并注入 extract(document, tool_hub)
• workspace 模板、prompt、skill 和主要文档改为推荐显式 ToolHub 注入写法
• console scripts 收敛为 tree-sitter-cli、xdev、xdev-config、agentic-extract、pdf-ai-explorer
• 移除 pyproject.toml 中的私有依赖解析 index，pdf-ai-explorer 改为仓库本地 wheel source

2026-04-24

修复 — DeepSeek thinking/tool-call 兼容

• agentic-extract 现支持显式 deepseek/<model_name> 前缀
• 官方 DeepSeek OpenAI 兼容端点会自动切换到 DeepSeekMultiAgentFormatter
• 避免在 DeepSeek chat.completions 路径上把 thinking 降级成普通文本，从而保留 reasoning_content
• 新增 test_model_factory.py 回归测试，覆盖 formatter 选择和 preserve_thinking 保护逻辑

修复 — structured output 探测兼容 DeepSeek JSON 模式

• probe_structured_output() 的探测 prompt 改为显式包含 json
• 避免 DeepSeek 因 response_format={"type":"json_object"} 且 prompt 未提及 json 而误报 probe 失败
• 新增对应 supervisor 回归测试

改进 — DeepSeek 默认配置与文档示例

• 工作区与全局 agentic-extract 配置中的标注模型默认切到 deepseek-v4-flash
• xdev / 提取链路相关示例统一改为 deepseek-v4-flash
• 主 agentic-extract 模型仍保留 deepseek-v4-pro 的推荐搭配

2026-04-23

新增 — agentic-extract 运行事件落盘与详细 agent 消息

• 默认将运行事件写入 workspace/.agent_state/events.jsonl
• RunRecorder 的阶段、迭代、step、heartbeat、完成/失败事件会落成 JSONL
• 基于 AgentScope hook 增加详细 agent 事件：agent_call_started、agent_message、agent_call_completed
• agentic-extract auto 路径补充 setup / prepare 相关事件，避免事件流只覆盖 run 主循环
• 新增 events.py 事件写入模块与配套测试，tests/agentic_extract 全量通过

新增 — 维护者 release-process skill

• 新增仓库本地 skill：docs/skills/release-process/
• 新增随包发布版 skill：src/agentic_extract/skills/release_process/SKILL.md
• README.md 与 docs/release_process.md 现在直接指向 release-process skill
• xdev export-skills 新增导出 release_process/SKILL.md

2026-04-20

改进 — agentic-extract CLI 预算控制与文档整理

• agentic-extract 默认预算改为 standard：max_iterations=10、agent_max_iters=25
• 新增 --budget fast：max_iterations=10、agent_max_iters=10
• 新增 --budget full：max_iterations=50、agent_max_iters=100
• 支持继续通过 --max-iterations、--agent-max-iters、--supervisor-max-iters、--business-max-iters、--dev-max-iters 显式覆盖预算
• CLI 启动时会输出预算摘要，方便确认本次运行的生效预算
• Supervisor 默认模式切换为 simple
• 新增聚焦 run / auto / budget 的 CLI 文档：docs/agentic_extract_cli.md

新增 — xdev-config 全局配置向导

• 新增独立命令 xdev-config
• 支持交互式、非交互式、混合补全和 --show 查看模式
• 同时写入 ~/.config/agentic-extract/config.json 与 ~/.config/xdev/config.json
• xdev 的 extract_tool 和 llm_select_tool 会同步使用同一套 extract-llm
• 新增 CLI 测试，覆盖打码展示、必填校验、增量更新与交互补全

改进 — PDF 解析默认使用 PPX CLI

• 默认 PDF → DocJSON 路径改为调用本机 ppx parse，不再依赖 memect_api_base
• 批量 PDF 解析统一走 ppx parse <dir> --workers N，新增 pdf_parse_concurrent / XDEV_PDF_PARSE_CONCURRENT 控制文件级并发，默认 1
• PPX 输出写入临时目录，xdev 只保存最终 .xdev/data/docjson/*.json 与 .xdev/data/pdf/*.pdf

改进 — xdev run 支持直接运行单个 PDF / DocJSON

• xdev run 新增 --pdf 与 --docjson 选项
• 现在支持三种单次提取输入：doc_id、单个 PDF、单个 DocJSON
• doc_id / --pdf / --docjson 三者必须且只能选一个
• 单个 PDF 会先通过本机 ppx parse 解析成 DocJSON，再复用现有 workspace 执行链

改进 — xdev 默认提取长度与配置展示

• extract_tool 与 llm_select_tool 的默认 max_content_length 统一为 50000
• xdev-config 的 --show 和写入前 summary 现在会展示 base_url、concurrent、pdf_parse_concurrent、memect_api_base、max_content_length，并补充 llm_select_max_content_length
• xdev-config 写入 ~/.config/xdev/config.json 时，如果缺少这些默认字段，会自动补齐 base_url、concurrent、pdf_parse_concurrent、memect_api_base、extract_tool.max_content_length 与 llm_select_tool.max_content_length

改进 — extract-agent 直接暴露 pdf-ai-explorer CLI

• pyproject.toml 的 project.scripts 新增 pdf-ai-explorer = "pdf_ai_explorer.cli:app"
• 现在安装 extract-agent 时，会一并暴露 pdf-ai-explorer 命令，减少二次安装步骤
• 更新安装文档，默认安装路径改为只安装 extract-agent

2026-04-15

重构 — agentic-extract 公共 Python API、运行期事件与状态落盘

• 新增低层 pure run API：run_agentic_extract() / run_agentic_extract_async()
• 新增高层 one-click API：run_agentic_extract_auto() / run_agentic_extract_auto_async()
• 新增公共类型：RunResult、IterationResult、ProgressEvent、TokenUsage、PrepareSpec
• 新增 callback 形式的稳定粗粒度进度事件与 heartbeat，运行中可持续接收 phase / iteration / step / heartbeat 进度
• 新增运行期 recorder 与 token usage 聚合，结果中可获得 iteration_count、每轮迭代时长、总迭代时长、总运行时长，以及 cache / reasoning token 明细
• CLI agentic-extract run 已切换为低层 pure run 适配层
• CLI 新增 agentic-extract auto，负责 bootstrap + run
• RunRequest / run_agentic_extract_request*() 已标记为兼容层，不再推荐给新调用方
• state.py 的迭代记录已扩展为结构化字段：started_at、finished_at、duration_sec、token_usage、summary、error
• 删除旧入口 src/agentic_extract/loop.py
• 新增并更新测试：test_api.py、test_runtime.py、test_usage.py、test_runner.py、test_cli.py、test_state.py
• 新增当前使用文档：agentic_extract_guide.md

2026-04-14

修复 — xdev eval 评估结果属性透传

• 修复 xdev.evaluation_result.EvaluationResult 未透传底层评估对象属性的问题
• xdev eval 现在可以正常访问 overall_accuracy、total_records、field_stats 等属性并打印完整评估报告
• 为 run_evaluation() 补充集成测试，覆盖 field_stats 和 total_records 的兼容访问

删除 extract_dev 和 llm_standard_generator，迁移功能到 xdev

删除模块：

• extract_dev/ - 旧评估模块，功能已迁移到 xdev
• llm_standard_generator/ - 未使用的 LLM 标准生成模块

新增 xdev 功能：

• xdev/extract.py：extract_from_docjson 支持 workspace/program/config 三种模式
• xdev/evaluation_result.py：EvaluationResult 替代 EvaluationResultWithMetadata
• xdev/html_report.py：HTML 报告生成（PDF 链接从 manifest 读取，无则留空）
• xdev/evaluation.py：run_evaluation 返回 EvaluationResult

版本：0.2.1 → 0.3.0

2026-04-07

重构 — 删除冗余模块并清理依赖

删除模块：

• agentscope_agent/ - 已被 agentic_extract 完全替代，删除全部 44 个文件
• fact_extract/ - 未使用的事实提取 pipeline，删除全部 28 个文件
• simple_workflow/ - 未使用的工作流模块，删除全部 28 个文件

依赖清理：
从 pyproject.toml 移除 14 个未使用的依赖：

• Web 框架：fastapi, uvicorn, websockets, python-multipart
• 数据库：sqlalchemy, alembic, psycopg2-binary
• 任务队列：celery, flower, redis
• 其他：openpyxl, fact-analyze, pysbd

Bug 修复：

• 修复 scripts/agentic_batch.sh 中的 API 认证冲突问题：在子进程中 unset ANTHROPIC_* 环境变量，避免与 .agentic-extract.json 配置文件中的 api_key 冲突

影响：

• 代码量减少：删除 25,705 行，新增 2,267 行（主要是 uv.lock 更新）
• 包体积减少：wheel 从 2.2MB 降至 1.9MB
• 核心模块 agentic_extract 功能不受影响，所有测试通过

2026-04-02

改进 — agentic-extract BusinessAgent prompt 重写 + 异常处理 + Supervisor simple 模式

• BusinessAgent prompt 重写：新增"每次回复必须包含工具调用"强制规则，明确 business_guide.md 和标注文件的位置与写入方式（含 write_text_file 示例），禁止读取 program.py/tests/（DevAgent 职责），禁止写 python 脚本解析 docjson
• Agent 异常处理：BusinessAgent 和 DevAgent 调用增加 try/except，异常时打印错误信息并继续循环，避免静默中断
• Supervisor simple 模式：新增 --supervisor simple CLI 选项，Supervisor 不注册任何工具，仅做纯决策路由；适用于 reasoning 模型（如 gpt-5.4）避免 think 模式下工具调用不稳定
• Supervisor task 描述优化：task 改为直接指令形式（"运行 xdev doc 查看文档，创建 business_guide.md"），禁止使用"请业务侧提供…"等间接表达
• Agent 状态目录迁移：agent memory 从 logs/agent_memory/ 迁移至 .agent_state/，避免与运行日志混淆
• xdev doc 长文档提示优化：pdf-ai-explorer 命令示例补全（outline/search/read/content），修正参数顺序
• xdev SKILL.md 精简：移除 --data-dir 全局选项描述（workspace 内工作时无需指定）

2026-03-20

改进 — agentic-extract supervisor loop 优化

解决 Agent 不查看真实文档、不校验字段名、评估信息丢失、无停滞检测等问题：

• 评估结果结构化：_run_xdev_eval 解析完整 xdev eval 报告（字段级准确率、错误文档 ID、字段平均），EvaluationSnapshot 新增 field_average、error_count、error_doc_ids、field_accuracies、report_text 字段
• evaluate action 反馈增强：Supervisor 收到字段级准确率 + ⚠ 标记 + 错误文档列表，而非仅 "准确率 X%"
• 停滞检测：连续 call_dev 未评估计数器，3 轮建议评估，6 轮强制提醒
• Schema 字段注入：每次 call_dev 实时读取当前 schema 字段名注入 task（schema 可能被 BusinessAgent 更新）
• 首轮 workspace 状态注入：第 1 轮 Supervisor 消息包含 schema 字段、文档数、标注数、program.py 存在性
• Supervisor prompt 增强：新增首轮要求（先了解数据再决策）、task 内容规范（包含具体字段/文档ID）、停滞提醒说明
• 迭代摘要增强：get_recent_summary 从 3 轮扩展到 5 轮，追加准确率趋势

改进 — agentic-extract supervisor 决策增强

• Supervisor 决策解析重构：支持单行 JSON、markdown 代码块、多行 JSON 三种格式
• 新增 structured output 探测：启动时自动测试模型是否支持 structured output（_probe_structured_output），可用时优先使用
• 决策重试机制：文本解析失败后自动发送格式提示并重试（最多 2 次）
• SupervisorDecision 改用 Literal 类型约束 action 取值，模糊匹配纠正大小写
• Supervisor prompt 精简：两阶段工作流（调查→决策）+ 格式提醒追加到 system prompt
• Business/Dev Agent prompt 新增「工作方式」指引（读取→修改→验证，避免重复读文件）
• 新增 --preserve-thinking 选项：ThinkingToTextWrapper 将 thinking blocks 转为 text blocks，防止 extended thinking 模型循环
• 新增依赖：fact-analyze（本地 editable 包）

新增 — fact-extract analyze pipeline

• 新增 analyze CLI 命令：委托 fact_analyze 包，执行实体→事件→关系→时间线全流程
• 新增 document.py：输入适配器，PDF/docjson/纯文本 → document.json 格式
• 新增 entity_identify.py：实体识别+消歧 → entities.json
• 新增 entity_attributes.py：实体属性提取 → entity_attributes.json
• 新增 entity_relations.py：段落级实体关系提取 → entity_relations.json
• 新增 event_extract.py：事件提取 → events.json
• 新增 event_relations.py：事件关系发现 → event_relations.json
• 新增 timeline.py：纯规则时间线合成 → timeline.json
• 新增 _batch.py：共享的按字数切分 batch 工具
• auto_section.py 新增 system_prompt 和 intermediate_dir 参数

2026-03-16

改进 — fact-extract section-mode 与默认后端调整

• --auto-section 标志替换为 --section-mode 选项，支持三种模式：
  • docjson（默认）：按原始 section 节点合并文本
  • line：每个 textline 作为独立 evidence item
  • auto：LLM 自动分段（等同原 --auto-section）
• evidence.py 中 extract_evidence_items() 新增 section_mode 参数，重构为统一分发逻辑
• 新增 _split_section_lines() 函数，支持行级粒度的 evidence 拆分
• 默认 extractor-backend 从 agentic 改为 llm-once（extract-task/run-workers/run 三处）
• 删除 src/fact_extract/SKILL.md（已迁移到本地 skills 目录）

改进 — tiktoken 离线缓存迁移到公共模块

• 将 tiktoken 缓存文件从 agentscope_agent/data/ 迁移到 extract_agent_common/data/tiktoken/
• 新增 extract_agent_common/tiktoken_cache.py：ensure_tiktoken_cache() 使用 importlib.resources 定位缓存目录
• agentic_extract/cli.py 和 agentscope_agent/cli.py 统一调用此...