deepseek-automation

name: deepseek-automation description: Use when implementing, resuming, reviewing, or verifying the DeepSeek++ Codex-style automation feature in this repository. Covers reading docs/progress/MASTER.md, following GitHub Issues #1-#16, preserving the background scheduler plus DeepSeek main-world runner architecture, recording telemetry, and updating progress for the automation implementation plan.

DeepSeek Automation

Use this project-local skill for the DeepSeek++ automation implementation. The feature goal is: create Codex-style automations that can run immediately in a new DeepSeek chat session and then continue in that same automation session on a cron/RRULE-like schedule.

Start Every Session

1. Read docs/progress/MASTER.md.
2. Confirm tracking mode. Current mode is GITHUB_STANDARD.
3. Query GitHub before starting work:

gh issue list -R zhu1090093659/deepseek-pp --label "spec-driven" --state open --json number,title,labels,milestone

4. Pick the next open issue in dependency order unless the user names a task.
5. Read the selected Issue body and linked local docs under docs/analysis/ and docs/plan/.
6. Update docs/progress/MASTER.md Current Status at session start and end.

Architecture Rules

• Keep scheduling in background code.
• Keep actual DeepSeek request execution in the DeepSeek page main-world context.
• Use content script only as a narrow bridge between background and main world.
• Do not add automation business logic directly into fetch-hook.ts unless the task is explicitly about hook compatibility.
• Prefer new focused files under core/automation/.
• Do not rely on background-only fetch('/api/v0/chat/completion') for MVP; DeepSeek web completion has challenge/proof-of-work behavior.
• Preserve existing memory, skill, preset, and tool-call behavior unless the Issue explicitly changes it.

DeepSeek Web Facts

Verified on 2026-05-21:

• Completion endpoint: /api/v0/chat/completion.
• History endpoint: /api/v0/chat/history_messages.
• Completion request fields include chat_session_id, parent_message_id, model_type, prompt, ref_file_ids, thinking_enabled, search_enabled, action, and preempt.
• New session and same-session continuation work from the web UI.
• Reload restores the automation test session from history.
• Persist the latest valid parent message id after every run and reconcile it against history.

S.U.P.E.R Principles

S - Single Purpose

From Unix philosophy.

• Each module, file, and function solves exactly one problem
• Prefer decomposition; power comes from composition
• One skill does one thing, one worker does one thing, one script does one thing

Litmus test: if you cannot describe a module's responsibility in a single sentence, it needs to be split.

Anti-pattern: a script that fetches data, computes metrics, renders charts, and sends notifications.

Correct approach:

fetch_data.py  -> data retrieval only, outputs JSON
compute.py     -> computation only, reads JSON writes JSON
render.py      -> rendering only, reads JSON generates HTML
notify.py      -> notification only, reads JSON calls webhook

U - Unidirectional Flow

From Clean Architecture.

• Data always flows in one direction: input -> processing -> output
• Dependencies always point inward: outer layers depend on inner layers, inner layers know nothing about outer layers
• No reverse dependencies, no circular calls

Layered model:

+-------------------------------+
|  Infrastructure (API, DB, UI) |  <- outermost, replaceable at will
+-------------------------------+
|  Adapters (transform, format) |
+-------------------------------+
|  Core business (pure logic)   |  <- innermost, zero external deps
+-------------------------------+

Litmus test: can the core logic run unit tests with zero external services? If not, the dependency direction is wrong.

P - Ports over Implementation

From Hexagonal Architecture.

• Define interface contracts (data structures, JSON Schema) before writing implementation
• Use intermediate formats (JSON files, standard data structures) to isolate upstream from downstream
• Swapping a data source, a rendering layer, or a notification channel requires zero changes to core logic

Practices:

1. Every module's input and output must be a serializable data structure
2. Module boundaries communicate via JSON files or standard data structures; in-process typed objects are fine, but cross-module interfaces must be serializable
3. Define explicit schemas - not "just read the code to figure out the format"

E - Environment-Agnostic

From 12-Factor App.

• Configuration injected via environment variables or config files, never hardcoded
• All dependencies explicitly declared (requirements.txt / package.json), no implicit reliance on global system packages
• Processes are stateless; all persistence delegated to external storage
• Logs go to stdout, not to files
• Same codebase runs on local machine, Cloudflare Workers, VPS, Docker

Configuration precedence:

Environment variables > .env file > config.json > in-code defaults

Checklist:

• All API keys and webhook URLs read from environment variables?
• All dependencies explicitly declared in a dependency file?
• No hardcoded file path assumptions?
• Can a different machine run this code with zero modifications?

R - Replaceable Parts

The natural consequence and ultimate goal of S + U + P + E.

• Any layer can be replaced without affecting others
• Replacement cost is the core metric of architecture quality
• If replacing one component triggers cascading changes in unrelated modules, the architecture is broken

Replacement matrix:

S.U.P.E.R Code Review Checklist

Run this before marking any task done.

1. The touched files each have one clear responsibility.
2. New automation logic is not dumped into fetch-hook.ts, content.ts, or background.ts when a focused module would do.
3. Data flows sidepanel/alarm -> background -> content -> main-world -> result without circular imports.
4. Cross-boundary messages have explicit TypeScript contracts.
5. Persisted objects are serializable and migration-friendly.
6. DeepSeek-specific behavior is isolated behind runner/history helpers.
7. Chrome-specific behavior is isolated behind background/tab orchestration helpers.
8. Errors are structured enough for run history and UI display.
9. The implementation can be tested or type-checked without a live DeepSeek page where possible.
10. npm run compile passes, or the blocking reason is recorded.

Scoring rule: all pass = proceed; 1-2 fail = fix first; 3+ fail = stop and refactor.

Phase Guidance

• Phase 1: implement contracts, store, and schedule calculation first.
• Phase 2: add scheduler and bridge; keep the main-world runner isolated.
• Phase 3: add Automation UI after store contracts are stable.
• Phase 4: add tab/login failure handling, timeouts, retry/missed-run policy, and prompt injection compatibility.
• Phase 5: verify live DeepSeek behavior and document limitations.

Progress and Telemetry

For every completed Issue:

1. Comment on the GitHub Issue with actual effort, S.U.P.E.R score, unplanned dependency count, files changed, and verification.
2. Update docs/progress/MASTER.md Current Status and phase counts if needed.
3. If a drift threshold in the milestone description is reached, stop and replan before continuing.

Archive Trigger

When all GitHub Issues are closed and all milestones are complete, enter archive mode:

1. Move docs/analysis/, docs/plan/, and docs/progress/ into docs/archives/deepseek-automation/.
2. Move this skill to docs/archives/deepseek-automation/skill/SKILL.md.
3. Update docs/archives/README.md.
4. Close milestones if they are still open.