Skip to content

feat: add capabilities and overview commands to cut agent probe calls - #154

Merged
codeasier merged 2 commits into
mainfrom
feat/issue-142-capability-overview
Sep 19, 2026
Merged

codeasier merged 2 commits into
mainfrom
feat/issue-142-capability-overview

Conversation

@codeasier

Copy link
Copy Markdown
Owner

📝 Description

Add two read-only discovery commands so agents can stop probing templates one by one and stop shelling out to sqlite3:

  • pt-snap capabilities — CLI version, full template/parameter contracts (including field semantics), and skill listing
  • pt-snap overview [database.db] — device list, per-device first/last event id, import-metadata status

Both --json paths reuse the existing success/error envelope. New packaged templates preexisting_live and freed_block_lifetime replace the leak skill's sqlite3 fallbacks. Leak prerequisite probes drop from 7 calls to 2 (capabilities + overview). Helper routes overview-first, then diagnose; it still does not auto-install, import pickle, or persist focus.

🔗 Related Issue

Fixes #142

Related to the Agent-friendly parent roadmap (issue 136) only. This slice must not auto-close that parent.

🧪 Testing

  • Tests added/updated
  • Focused capability/overview/template/leak/helper/CLI/API/contract cases
  • Broader suite via worktree PYTHONPATH=src: tests/test_cli.py tests/test_cli_json.py tests/test_contract_cli_api.py tests/query/ tests/skills/test_helper_contract.py tests/test_api.py plus new service/template/leak files — 421 passed
  • ruff check and black --check on touched Python paths
  • basedpyright
  • Full pytest suite
  • Manual testing completed

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    Snapshot provenance decision: no-update
    Snapshot provenance no-update reason: This PR adds CLI discovery commands, core services, query templates, skills, tests, and docs. It does not modify src/pt_snap_cli/snapshot/**.

📋 Additional Notes

@codeasier codeasier left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

交叉评审结论(3 位独立评审 + 裁决核验)

3 位评审员(qwen3.8-flash / deepseek-v4.1-flash / muse-spark-1.3-contributor)全部完成,全部候选发现已逐条对照 PR 头快照证据核验。无严重/高危发现;5 个低危发现存活,均以行内评论标注:

  1. capabilities 缺少失败信封(SkillCatalogError → traceback)
  2. overview 设备边界路径可泄漏原始 ValueError / sqlite3.OperationalError
  3. preexisting_live 在 event_id <= -2 时把 static 块计入,违反自身谓词等价声明
  4. SnapshotAnalyzer.get_database_overview 遗漏 FocusFileInvalidError 映射
  5. 模板契约序列化器三份平行副本,无 --template-info 交叉校验

其余核验通过:两命令均只读(mode=ro,无 focus 持久化)、模板 SQL 无注入面、preexisting_live / freed_block_lifetime 在正常输入下与被替换的旧逻辑等价、skill 仓库版与打包版字节一致、en/zh 文档同步更新。

遗留缺口:PR 自述未跑 basedpyright 与完整 pytest(checklist 两项未勾选),合并前建议补齐;overview 的 DATABASE_NOT_FOUND / DATABASE_SCHEMA_INVALID / FOCUS_FILE_INVALID 错误信封路径目前无测试。

注:本评审由并行多模型交叉评审产生,增加了 token 用量与成本。

Comment thread src/pt_snap_cli/cli.py Resolved
Comment thread src/pt_snap_cli/context.py Resolved
Comment thread src/pt_snap_cli/api.py Resolved
Comment thread src/pt_snap_cli/core/query_service.py Resolved
codeasier pushed a commit that referenced this pull request Sep 19, 2026
Review of #154 found traceback leaks and a preexisting_live static-block
edge case that broke the #138 agent contract and the template's own
predicate claim. Map those paths to stable errors and one shared
template-info serializer.
@codeasier

Copy link
Copy Markdown
Owner Author

交叉评审跟进:a4d137e 全部核验通过

5 个低危发现已在 a4d137e 逐一对照源码核验,并在各评论线程回复确认。验证方式:检出 a4d137e 后本地运行——

  • 聚焦测试(test_cli_json.py / test_context.py / tests/core/test_overview_service.py / tests/query/test_leak_fallback_templates.py / test_api.py / test_contract_cli_api.py):100 passed
  • ruff check + black --check(4 个改动源文件):通过
  • basedpyright:0 errors(974 warnings 为既有信息级,snapshot/ 规则已降级)——补上了此前遗留缺口中的类型门禁

补充确认:overview 的 DATABASE_NOT_FOUND / DATABASE_SCHEMA_INVALID / FOCUS_FILE_INVALID 错误信封测试也随本提交补齐。评审侧无进一步意见;合并前仅剩完整 pytest 套件(CI)确认。

codeasier added 2 commits September 19, 2026 19:59
Give agents one-shot catalog and read-only database orientation so leak diagnosis no longer needs per-template --template-info or sqlite3 CLI fallbacks.

Fixes #142
Review of #154 found traceback leaks and a preexisting_live static-block
edge case that broke the #138 agent contract and the template's own
predicate claim. Map those paths to stable errors and one shared
template-info serializer.
@codeasier
codeasier force-pushed the feat/issue-142-capability-overview branch from a4d137e to 2fbf5cb Compare September 19, 2026 12:00
@codeasier
codeasier merged commit a84598a into main Sep 19, 2026
6 checks passed
@codeasier
codeasier deleted the feat/issue-142-capability-overview branch October 3, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] 能力清单与数据库概览:减少 Agent 前置探测调用

1 participant