Eudic Anki Pipeline (Skill Unificada)

O que Eudic Anki Pipeline (Skill Unificada) faz?

Público

Este arquivo é para o agente executor. O usuário fornece objetivos em linguagem natural; o agente executa de ponta a ponta.

Distribuição

Esta skill reside em skills/eudic-to-anki/ no repositório de origem, para que possa ser instalada com a CLI do Vercel Skills (npx skills add <owner>/<repo> --skill eudic-to-anki). Após a instalação, trate este diretório (onde SKILL.md reside) como o diretório de trabalho atual para todos os comandos abaixo. Consulte o README.md raiz do repositório para a linha de instalação exata assim que o repositório estiver público no GitHub.

Escopo

Skill única, módulos internos:

• Módulo de exportação: modules/export/README.md
• Módulo de coach: modules/coach/README.md
• Módulo de importação: modules/import/README.md
• Módulo de áudio: modules/audio/README.md
• Playbooks de fluxo de trabalho: workflows/*.md

Todos os comandos abaixo assumem que o cwd é a raiz da skill: eudic-to-anki/.

Padrões

• Data: ontem (fuso horário local) a menos que o usuário especifique um intervalo.
• Fonte: todas as categorias do Eudic, a menos que o usuário especifique uma categoria.
• Deck: words a menos que o usuário especifique.
• Tipo de nota: TRVS-Lab.
• Artefatos intermediários: apenas o diretório de artefatos de documentos dedicado do usuário. Use a forma absoluta canônica <ABS_TEMP_DIR>, como /Users/alice/Documents/eudic-to-anki-temp.
• Substituição opcional para testes locais/configurações personalizadas: EUDIC_TO_ANKI_TEMP_DIR=/caminho/para/temp.
• Para execuções sensíveis a regras, expanda os caminhos dos artefatos para um diretório absoluto como /Users/alice/Documents/eudic-to-anki-temp; não os execute com ~ ou $HOME.

Disciplina de Execução

<ABS_TEMP_DIR> abaixo significa o diretório de artefatos expandido do usuário, por exemplo /Users/alice/Documents/eudic-to-anki-temp.

• Execute comandos cobertos por regras apenas como comandos argv diretos.
• Não os envolva em /bin/zsh -lc ..., zsh -lc ..., bash -lc ..., env ..., ou FOO=bar ....
• Não encadeie com &&, ||, ;, pipes, ou subshells ao redor de um comando coberto por regras. Execute a preparação e o comando principal como chamadas de ferramenta separadas.
• Quando o cwd for a raiz da skill, use caminhos de script relativos como python3 scripts/eudic_export.py ....
• Quando o cwd for outro local, use caminhos absolutos da skill instalada como python3 /Users/alice/.agents/skills/eudic-to-anki/scripts/eudic_export.py ....
• Se o zsh de login for necessário para carregar tokens, chame python3 scripts/run_with_login_zsh.py python3 scripts/eudic_export.py ... diretamente; não adicione outro wrapper de shell ao redor.
• Se <ABS_TEMP_DIR> não existir, crie-o primeiro com um comando direto separado: mkdir -p /Users/alice/Documents/eudic-to-anki-temp.

Início Rápido (fluxo do agente)

1. Garanta que o diretório temporário existe:
   • mkdir -p <ABS_TEMP_DIR>
2. Verificação de ambiente:
   • bash scripts/check_env.sh
3. Exportar palavras:
   • python3 scripts/eudic_export.py --all-categories --start-date <D> --end-date <D> --format csv --output <ABS_TEMP_DIR>/_day_<D>_export.csv
4. Construir placeholder + coach do autor:
   • python3 scripts/build_dia_json_from_csv.py --csv <ABS_TEMP_DIR>/_day_<D>_export.csv --output <ABS_TEMP_DIR>/_day_<D>_partial.json --batch-date <D> --eudic-words-only
   • O agente escreve o JSON do coach refinado. Cada nota deve incluir part_of_speech, e cada linha de meaning deve começar com um marcador de POS como n., vt., vi., adj., ou adv.. Em seguida, mescle (arquivo único ou lotes + scripts/merge_coach_with_partial.py).
5. Validar:
   • python3 scripts/validate_trvs_coach_json.py <ABS_TEMP_DIR>/_day_<D>_import.json
6. Importar com áudio (importação bem-sucedida aciona sincronização Anki por padrão; use --no-sync para pular):
   • python3 scripts/ankiconnect_import.py --input <ABS_TEMP_DIR>/_day_<D>_import.json --deck words --create-deck --dia-upsert --audio-provider command --audio-format mp3 --audio-command 'python3 scripts/edge_tts_runner.py --text "{word}" --output "{output}"''
   • --audio-command é analisado como argv e executado sem um shell; operadores de shell como pipes/redirecionamento não são suportados.
7. Limpeza após sucesso:
   • bash scripts/cleanup_import_artifacts.sh

Portões de Qualidade

• O agente escreve o conteúdo do coach; não copie em massa exp/phon do Eudic para campos do coach por padrão.
• O JSON do coach deve preservar POS explicitamente: inclua part_of_speech em cada nota e mantenha marcadores de POS no início de cada linha meaning em chinês.
• Para listas grandes, use subagentes em lote e valide cada lote antes de mesclar.
• Se a saída do subagente for base64, decodifique via:
  • python3 scripts/decode_subagent_transcript_b64.py <subagent.jsonl> -o <ABS_TEMP_DIR>/coach_batch_01.json
• Bloqueie a importação em erros do validador (U+FFFD, marcadores mojibake, tipos de campo errados, marcadores de POS ausentes em meaning ou part_of_speech ausente).
• Após uma importação bem-sucedida, ankiconnect_import.py executa a sincronização do Anki por padrão; passe --no-sync para pular.
• Se a validação falhar (especialmente formato root), regenere apenas o lote/palavras com falha e execute o validador novamente antes de mesclar/importar.

Playbooks

• Fluxo de ontem: workflows/yesterday.md
• Fluxo de intervalo de datas: workflows/date-range.md
• Fluxo de lista de palavras do usuário: workflows/word-list.md

Segurança

• Nunca armazene valores de token em arquivos rastreados.
• Prefira EUDIC_TOKEN do ambiente.
• Se o AnkiConnect não estiver disponível, pare e forneça orientação de configuração.