doctor-link 0.6.0

Universal diagnostic and AI collaboration tool for software debugging.

Doctor link

Doctor link is a local-first, human-AI shared diagnostic and verified-repair layer for software projects.

Doctor link 是一个本地优先、面向软件项目的人机协同诊断与修复验收层。它不仅组织问题、证据和 AI 上下文，还能在明确授权后驱动 Codex 修复 Python 或 Node.js JavaScript/TypeScript 项目，并独立重测是否真正解决。

• English documentation
• 中文文档
• GitHub repository guide

Why Doctor link

AI coding tools can edit code quickly, but they still need reliable context. Doctor link helps a person and an AI tool agree on:

• what the problem is;
• which evidence supports it;
• which claims came from a human;
• which commands reproduced the behavior;
• what changed before and after a fix;
• which checks are required before closure.

Doctor link does not replace Codex, Cursor, Aider, OpenHands, Continue, Cline, Windsurf, or similar tools. It prepares a structured, privacy-aware diagnostic package that those tools can consume.

Verified status

Latest published version: v0.6.0. The release workflow publishes the immutable GitHub assets first, followed by the same validated artifacts on PyPI.

The v0.5 line passed 365 tests, all 66 installed CLI routes through 75 invocations and twelve complex scenarios, and Python 3.10–3.14 plus Ubuntu, macOS, Windows, packaging, security, Trusted Publishing, and clean pipx installation gates.

Evidence:

• cloud validation certificate
• validation evidence index
• v0.6.0 release notes

Main capabilities

Capability	What it provides
Preflight	Read-only inspection of project configuration, commands, catalogs, Python version, and local tools.
Diagnostic packages	Structured reports, summaries, evidence indexes, timelines, problem maps, and machine-readable JSON.
Evidence collection	Logs, attachments, environment metadata, command results, redaction records, and integrity indexes.
Human assertions	Explicit records of user-confirmed problems that AI output must not silently dismiss.
Reproduction and tests	Shell-free configured command execution, test matrices, evidence write-back, and timeout metadata.
Guided problem solving	Ordinary-language problem matching, ranked safe reproduction checks, local browser results, and repair preview without requiring test-command knowledge.
Automatic solve	Python and Node.js JavaScript/TypeScript failure reproduction, explicit repair approval, isolated Git branch, bounded Codex rounds, protected verification inputs, and independent regression acceptance.
Verification	Missing-evidence reporting, linked assertion coverage, failed-test blockers, before/after comparison, and conservative closure status.
AI handoff	Tool-specific packages with explicit repair, evidence, and verification-review readiness states.
Local workbench	Static local HTML for reviewing diagnostic packages without a hosted service.
Security and privacy	Redaction, privacy scanning, export gates, integrity manifests, and explicit execution approval.
Extensibility	Adapter and plugin manifests with dry-run defaults, permission checks, and audit records.
Operations	CI reports, project health, local knowledge indexes, archives, and distribution readiness.

Quick start

Requirements: Git and Python 3.10 or later.

Current support scope:

• guided diagnosis and diagnostic packages for local software projects;
• verified automatic repair for clean Git repositories containing Python or Node.js JavaScript/TypeScript projects;
• Node.js repair requires the project's package manager and runtime;
• automatic edits require an installed, authenticated Codex CLI and explicit --allow-repair approval;
• other language ecosystems are not yet supported.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install doctor-link==0.6.0
doctor-link --version
doctor-link preflight . --json

For the simplest path, describe the problem and let Doctor link find and validate a reproduction:

doctor-link assist /path/to/project --problem "Checkout duplicates a charge"

On Windows PowerShell, activate the environment with:

.\.venv\Scripts\Activate.ps1

Create a first diagnostic package:

doctor-link report . --out DoctorReports
PACKAGE_DIR=$(find DoctorReports -mindepth 1 -maxdepth 1 -type d | head -n 1)
doctor-link collect "$PACKAGE_DIR" --project-root . --command "python --version"
doctor-link verify "$PACKAGE_DIR" --write-back
doctor-link view "$PACKAGE_DIR" --build-only

See Quick Start and Installation for Windows alternatives and complete validation instructions.

Automatically solve a reproducible Python or Node.js-project problem:

# Preview only: reproduces the issue and writes the repair plan.
doctor-link solve /path/to/project \
  --problem "Checkout creates two charges" \
  --test-command "python -m pytest tests/test_checkout.py -q"

# Explicitly authorize branch creation and Codex edits.
doctor-link solve /path/to/project \
  --problem "Checkout creates two charges" \
  --test-command "python -m pytest tests/test_checkout.py -q" \
  --allow-repair

For a Node.js project with a non-placeholder scripts.test, Doctor link automatically selects npm test, pnpm test, yarn test, or bun run test from packageManager and lockfile evidence. If no test script exists but JavaScript test files are present, it falls back to node --test:

doctor-link solve /path/to/node-project \
  --problem "Concurrent updates lose the latest value" \
  --test-command "npm test" \
  --allow-repair

See Automatic Solve with Codex for command discovery, status codes, evidence files, and rollback.

For an npm, Yarn, or pnpm workspace, keep the repository root and select a package with --package packages/name. Interrupted repair receipts can continue with doctor-link solve --resume SESSION_DIR --allow-repair. Repeatable multi-project suites use doctor-link benchmark benchmark.yml --out DoctorReports/benchmark and report reproduction and repair-success metrics.

Typical diagnostic workflow

preflight → report → collect → assert → reproduce/test → verify → handoff/view

For the automatic Python or Node.js path, the complete workflow is:

solve preview → explicit approval → repair branch → Codex round → protected-input check → independent verification → verified/blocked/failed

1. preflight checks readiness without running repository commands.
2. report creates the diagnostic package.
3. collect adds reviewed evidence and command output.
4. assert records human-confirmed behavior.
5. reproduce and test execute explicitly configured checks without a shell.
6. verify identifies missing evidence and determines closure status.
7. handoff or view prepares AI context or a local review interface.

Failed reproductions, failed required test jobs, and incomplete verification return a non-zero exit code even when --json is used. See Automated diagnosis reliability for the complete evidence and status rules.

Safety model

• Doctor link is local-first and does not upload diagnostic packages by default.
• Reproduction and test-matrix commands do not invoke a shell; pipelines, redirection, command substitution, and unsafe operators are rejected.
• Adapter and plugin execution is dry-run by default and requires explicit --allow-run approval.
• Automatic code repair requires --allow-repair, a clean Git working tree, and a failing executable check. Codex remains sandboxed to workspace-write; Doctor link does not auto-commit or push.
• Automatic repair hash-protects tests, package manifests and lockfiles, test configuration, reproduction/test catalogs, and directly referenced verification scripts. Protected-input changes block verified; the explicit exception --allow-verification-changes returns review_required instead of success.
• --allow-repair invokes the authenticated Codex service and may send the bounded prompt, failing output, and inspected repository context. Review the preview and remove sensitive data before authorization.
• Generated packages may still contain project-sensitive evidence. Review privacy and redaction reports before sharing them.
• Do not attach secrets or private diagnostic packages to public GitHub issues.

Read SECURITY.md, sensitive data handling, and the export security checklist.

Development validation

python -m pip install -e '.[dev]'
ruff check doctor_link tests scripts
pytest -q --cov=doctor_link --cov-branch --cov-fail-under=85
bandit -r doctor_link -ll
pip-audit
python -m build
python scripts/validate_distribution_contents.py dist
python -m twine check dist/*
bash scripts/e2e_validate.sh "$(pwd)"
bash scripts/p7_runtime_validate.sh "$(pwd)"

GitHub Actions runs the full Python matrix, security checks, package installation, and cross-platform smoke checks for pull requests targeting main.

Repository map

Path	Purpose
doctor_link/	Python package and CLI runtime.
.doctorlink/	Repository-owned diagnostic strategies, catalogs, and configuration.
tests/	Unit, integration, regression, packaging, security, and documentation tests.
scripts/	E2E, self-validation, package-content, and release helper scripts.
schemas/	Versioned diagnostic package schemas.
examples/	Example projects, configurations, handoff data, and diagnostic packages.
docs/	User guides, architecture, validation evidence, release policy, and historical audits.
.github/	Issue template, PR template, Dependabot, CI, manual validation, self-validation, and release workflows.

Documentation map

• Quick Start
• Installation
• PyPI trusted publishing
• CLI reference
• Automated diagnosis reliability
• Automatic Solve with Codex
• Full capability validation
• Platform integration roadmap: English | 中文
• Support and maintenance: Support | Security | Compatibility and deprecation
• Product overview
• Architecture overview
• GitHub repository and workflow guide
• Contributing
• Security policy
• Project status
• Validation certification
• Release policy

Project boundaries

Doctor link currently does not provide a hosted web platform, cloud synchronization, an external account system, telemetry, a marketplace, production key management, hosted enterprise archives, hosted diagnostic knowledge bases, or production RBAC. Those capabilities must not be inferred from planning documents.

License

Doctor link is licensed under the MIT License.