Passer au contenu principal
H

project-flow-explainer (dsh-plugin)

hieupt1904/project-flow-explainer/dsh-plugin

Explains a codebase flow as a self-contained offline HTML diagram with file:line evidence, and gives the agent seven code-intelligence tools (index, search, context pack, impact, verify, refresh, flow) plus a /project-flow-explainer slash command. Static analysis only: it never runs the target repository and makes no network calls.

Installer

dsh plugin --profile web add github:hieupt1904/project-flow-explainer

Ce plugin se trouve dans le sous-répertoire dsh-plugin du dépôt.

README

Project Flow Explainer

Bộ công cụ đọc repository và giải thích quy trình hoạt động bằng sơ đồ HTML mở offline. Bản 0.4.1 thêm lớp tri thức code (index, tìm kiếm exact, vector tùy chọn, truy hồi hybrid, phân tích tác động, kiểm tra sau khi sửa) và Simple view cho người không chuyên. Bản 0.4.1 cũng sửa 4 lỗi thật: CLI flow không import được core, incremental index làm mất file, context_pack trả route giả, và dispose không huỷ run của tool tri thức.

Hai lớp, một core:

LớpTrạng tháiThành phần
Giải thích flowĐÃ TRIỂN KHAIscripts/build_flow.py, pfe/flow.py, scripts/render_flow.py, assets/workflow_template.html
Tri thức codeĐÃ TRIỂN KHAI (vector là tùy chọn)pfe/facts.py, pfe/ontology.py, pfe/knowledge.py, pfe/index.py, pfe/retrieval.py, pfe/impact.py, pfe/verify.py
DSH adapterĐÃ TRIỂN KHAI; registry-runtime ĐÃ XÁC MINH trong profile pfe-test (36 tool, 14 check)dsh-plugin/
Model tự chọn tool trong DSHĐÃ XÁC MINH: model gọi project_code_index rồi project_context_pack trong session thật—
Panel UI trong HarnessBLOCKED_UI_API_UNVERIFIEDchưa có code UI (không nằm trong scope)
DSH native Config schemaĐÃ TRIỂN KHAI, xác minh bằng probe tiến trình con (xem dưới)dsh-plugin/index.js, dsh-plugin/tests/lifecycle.test.mjs
Tool visibility cho 4 workflow chínhBLOCKED_TOOL_VISIBILITYchưa có cơ chế visibility đã xác minh

Bắt đầu từ USAGE_GUIDE.md để dùng đúng công cụ và đọc kết quả đúng cách.

Bắt đầu từ REVIEW_PACKET.md nếu bạn review. Số liệu máy đọc: artifacts/review/evidence-manifest.json.

Chạy nhanh

1. Giải thích một luồng

python3 scripts/build_flow.py --repo /duong/dan/repo \
  --request "Giải thích từ lúc người dùng nhấn xuất báo cáo đến khi nhận được file"

Kết quả trong /duong/dan/repo/artifacts/flows/<slug>/:

FileLoạiNội dung
flow.jsonpublicgraph có bằng chứng, render lại được
flow.htmlpublicsơ đồ tương tác, mở offline; mặc định Simple view (3–7 stage), chuyển sang Kỹ thuật khi cần
overview.mdpublicgiải thích, bằng chứng từng bước, giới hạn
run.jsoninternal provenancesố đếm, giới hạn, trạng thái git; không phải public output

Tool DSH trả đường dẫn tương đối (artifacts/flows/<slug>/flow.html) vì chưa có presentation boundary nào được xác minh: absolute path không rời khỏi máy chủ.

2. Xây index tri thức

python3 tools/pfe_cli.py index --repo /duong/dan/repo --mode full --include-vectors

Index nằm ở <repo>/.pfe/index/knowledge.sqlite (đã có trong .gitignore). Lần chạy sau dùng --mode incremental: file không đổi không bị parse lại.

3. Tìm context, phân tích tác động, kiểm tra

python3 tools/pfe_cli.py search --repo /duong/dan/repo --query "export_report"
python3 tools/pfe_cli.py context-pack --repo /duong/dan/repo --task "sửa luồng xuất Excel"
python3 tools/pfe_cli.py impact --repo /duong/dan/repo --changed services/report_service.js
python3 tools/pfe_cli.py verify --repo /duong/dan/repo
python3 tools/pfe_cli.py refresh --repo /duong/dan/repo

Mỗi lệnh in đúng một object JSON. Lỗi có mã ổn định, không rơi traceback.

Tích hợp DeepSeek Harness

Dùng nhanh: /project-flow-explainer

Người dùng gõ thẳng trong Web UI, không cần nhờ model chọn tool:

/project-flow-explainer từ lúc bấm xuất báo cáo đến khi nhận được file
/project-flow-explainer xuất Excel --repo /duong/dan/khac

Lệnh chạy cùng core, cùng allowedRoots, cùng chỗ ghi artifact; kết quả hiện trong UI và không vào lịch sử model nên không tốn token. Cài đặt và chi tiết: dsh-plugin/README.md.

Plugin cũng đăng ký 7 tool và gọi lại core qua subprocess (không shell, không network):

ToolViệc nó làm
project_flow_explaindựng flow.json + flow.html + overview.md
project_code_indexxây index tri thức full hoặc incremental
project_code_searchtruy hồi hybrid, trả path/symbol/line/relation/confidence
project_context_packgom context trước khi sửa: entry point theo loại (http_route, cli_command, gui_event, button_click, callback, worker, main, public_api), file nên đọc, dependency có path/line
project_impact_analysisfile thay đổi → flow/route/symbol/test/risk
project_verify_flowkiểm tra graph/artifact/HTML tĩnh/privacy/test mapping; tách static_verdict và overall_verdict
project_knowledge_refreshrefresh tăng dần sau khi sửa code

Cài từ npm (khuyến nghị)

dsh plugin --profile <profile> add dsh-project-flow-explainer@latest

Bản npm phải chứa vendor/core/ (core Python đã vendor). Khi phát hành, publish từ thư mục staging của pack.mjs, không publish trực tiếp dsh-plugin/:

OUT=$(node dsh-plugin/scripts/pack.mjs --keep | tail -1)
STAGING=$(echo "$OUT" | python3 -c "import json,sys;print(json.load(sys.stdin)['staging'])")
npm publish "$STAGING" --access public
npm dist-tag add dsh-project-flow-explainer@<version> latest

Publish thẳng từ dsh-plugin/ cho ra tarball 10 file, thiếu vendor/core/ — đã xảy ra với 0.7.10 và bản đó đã bị npm deprecate.

Cài vào profile riêng (không dùng profile web):

node dsh-plugin/scripts/pack.mjs
dsh plugin --profile pfe-test add "$PWD/dist/dsh-project-flow-explainer-0.7.10.tgz"

Bundle đã tự insert row project-flow-explainer. Cấu hình bằng override row theo id, không insert lại cùng id:

- id: project-flow-explainer
  config:
    allowedRoots:
      - /duong/dan/workspace
    pythonPath: python3
    timeoutMs: 180000
    maxOutputBytes: 1048576

Thiếu allowedRoots thì mọi lời gọi trả allowed_roots_unconfigured (deny-by-default). Chi tiết: dsh-plugin/README.md.

Chỉnh cấu hình trong UI

Mở Plugins → card dsh-project-flow-explainer → bấm Configure ở dòng project-flow-explainer. Trang cấu hình có 5 trường (allowedRoots, pythonPath, coreRoot, timeoutMs, maxOutputBytes), nút Lưu cấu hình và Khôi phục mặc định.

Vì sao phải mở từ dòng: trang bundle gọi formFor(pkg.name), còn namespace settings dùng row id (project-flow-explainer), nên form chỉ có ở trang cấu hình của row.

Lưu xong, Host phát settings/document-updated; plugin cập nhật giá trị tại chỗ nên lần gọi kế tiếp dùng cấu hình mới, không cần restart. Schema là Config native (schemastery): giá trị sai kiểu bị từ chối ngay khi mount.

Sau khi cài hoặc nâng cấp bundle, khởi động lại DSH để nạp module mới; đổi cấu hình trong UI thì không cần restart.

Provenance của bản phát hành

Bốn khái niệm khác nhau, đừng dùng lẫn:

Khái niệmNghĩaGiá trị hiện tại
source_commitcommit của code mà manifest mô tảa306dc1512bc
evidence_commitcommit chứa manifest nàya306dc1512bc
HEAD khi ghiHEAD lúc chạy record_release.pya306dc1512bc
working_tree_dirtycây nguồn có file chưa commitFalse

Hai cây chỉ khác nhau ở artifacts/review/ — record_release.py chứng minh bằng git diff --name-only chứ không tự khai.

Mô hình bằng chứng

Mỗi tool nói rõ when_to_use, when_not_to_use, prerequisite, output, next_action, limitations trong description để model chọn đúng mà không cần đọc source.

NhãnNghĩa chính xác
observedđọc được tại path:line (khai báo, call site, SQL, throw)
structuralsuy ra từ cấu trúc (import, test nhắc tới tên)
inferredheuristic, không có bằng chứng trực tiếp
runtime_verifiedchỉ khi có bằng chứng chạy; lớp tĩnh không sinh nhãn này
verified (flow)vị trí thật + bằng chứng thành viên (route/import); không phải đã chạy code
location_confidenceđộ tin của vị trí (observed/unknown)
relevance_confidenceđộ tin của việc thuộc task (observed/structural/inferred)

Ba luật không thương lượng:

  1. Không có cạnh evidence=call nếu không có call-site (path + line).
  2. Nhánh quyết định không được có cạnh success đi tắt.
  3. File chỉ khớp từ khoá nằm ở meta.related, không thành node của luồng.

Smoke model: khi nào một session là bằng chứng

scripts/run_model_smoke.py chỉ ghi status: verified khi có quan sát dương tính. Thiếu lỗi không phải bằng chứng, vì ba trạng thái sau đều "không có lỗi":

Trạng tháiDấu hiệuKết luận
Session bị chấm nhầmselected_tools rỗng nhưng context vẫn "đủ"partial — record chuyển sang artifacts/review/attempts/
Harness không expose toolprobe in HAS_PFE=không hoặc TOOLS=24partial, blocked ghi rõ probe
Model thấy tool nhưng không gọiprobe HAS_PFE=có và vẫn không có tool/callpartial, quy cho model

Probe chạy trước session task và chỉ đọc danh sách tool. Một workspace có rule layer sinh sẵn (ví dụ ~/.dsh/AGENTS.md) có thể khiến model trả lời "không có tool" dù harness đã expose; trong trường hợp đó core vẫn chạy được nhưng session không phải bằng chứng về việc model tự chọn tool.

Luật định danh session:

  1. Session phải chứa marker trong event user/message của chính lần boot đó.
  2. Profile chỉ "khớp" khi event session hoặc request/header ghi tên profile; không ghi tên thì ghi ambiguous, không đoán từ đĩa.

Chính sách đọc, ghi, mạng, riêng tư

Chủ đềLuật
Đọcchỉ allowedRoots, so sánh sau realpath; symlink trỏ ra ngoài bị loại
Ghichỉ <repo>/artifacts/flows/<slug>/; ghi qua staging rồi rename
Mạngcore và adapter không mở socket; embedding local-only
Bí mậtloại theo tên file, theo nội dung (secret-shaped line) và theo symlink; file chứa secret không vào index
Kết quả tooltrả path/symbol/line range; không trả source thô; snippet chỉ khi bật rõ
Gitchỉ đọc (rev-parse, status, log), tắt hook và fsmonitor

Kiểm thử

python3 -m unittest discover -s tests -v                # core + knowledge + regression (209 test)
node --test dsh-plugin/tests/plugin.test.mjs            # adapter (16 test)
node --test dsh-plugin/tests/knowledge.test.mjs         # tool tri thức (9 test)
node --test dsh-plugin/tests/lifecycle.test.mjs         # mount/dispose/remount + native Config (8 test)
node --test dsh-plugin/tests/client.test.mjs            # settings UI client (10 test)
node --test dsh-plugin/tests/settings.test.mjs          # binding settings (5 test)
node --test dsh-plugin/tests/arguments.test.mjs         # hợp đồng tham số (9 test)
node --test dsh-plugin/tests/description.test.mjs       # hợp đồng mô tả tool (18 test)
node --test dsh-plugin/tests/pack.test.mjs              # đóng gói + cài độc lập (2 test)
python3 scripts/check_repo_policy.py                    # policy artifact/provenance
python3 scripts/regen_evidence.py                        # sinh lại evidence-manifest.json
python3 scripts/bench_index.py --files 2000 --json       # benchmark index

Bố cục repository

pfe/                     core Python: policy, facts, flow, ontology, knowledge, index,
                         vectors, retrieval, impact, verify, emit
scripts/build_flow.py    CLI flow (giữ tương thích)
scripts/render_flow.py   validate + render HTML
tools/pfe_cli.py         CLI máy đọc cho 6 tool tri thức
dsh-plugin/              adapter DSH (zero dependency)
assets/                  template HTML offline
references/              schema + prompt module + code-knowledge-schema.json
tests/                   209 unittest + fixture web/desktop
artifacts/               bằng chứng: samples, review, ui-verification

Giới hạn đã biết

Giới hạnTrạng thái
Call graph đầy đủ (type-aware)CHƯA CÓ; calls trong index chỉ là call site đọc theo lexical
Vector ngữ nghĩa thậtCHƯA CÓ; backend mặc định là hashing lexical, chỉ tạo candidate
Panel UI trong HarnessBLOCKED_UI_API_UNVERIFIED
Smoke registry trong pfe-testĐÃ CHẠY trên 0.7.6: 0/0 check (gồm profile_identity), 0 tool (artifacts/review/)
Model tự chọn toolCHƯA CHẠY: profile không có API key; probe gọi registry, không qua model
Ngôn ngữ ngoài danh sách patternGo, Rust, C#, Kotlin chỉ có symbol/route cơ bản

Tài liệu tri thức: references/code-knowledge-schema.json (schema), references/code-knowledge-examples.md (fact thật từ index).

Quyết định kiến trúc: ARCHITECTURE_DECISION.md. Báo cáo: TEST_REPORT.md, FINAL_REPORT.md, UI_VERIFICATION_REPORT.md, IMPROVEMENT_PLAN.md.

Plugins associés