TKO
Distribuição de tarefas de programação com Git, desenvolvimento na IDE do aluno e análise contínua do processo de aprendizagem.
O TKO é um ecossistema de ensino de programação centrado em prática, versionamento e evidências de aprendizagem. Ele distribui atividades via Git, permite desenvolvimento na IDE local e acompanha progresso de turmas com dados reais de evolução.
Visão Geral
O TKO resolve o problema de acoplar ensino de programação a ambientes artificiais de navegador. Em vez disso, o aluno trabalha no próprio fluxo profissional: editor, terminal, compilador e controle de versão.
Para o professor, o sistema viabiliza distribuição de tarefas personalizadas e acompanhamento de execução com sinais de desenvolvimento, como tempo de resolução, histórico de versões e progresso por atividade.
Fluxo rápido:
- Professor cria ou publica repositórios de questões.
- Aluno baixa a atividade e desenvolve na própria IDE.
- Aluno executa os testes localmente e itera com feedback imediato.
- Aluno envia para o professor via Git, normalmente por um repositório compartilhado no GitHub.
- Professor acompanha evolução, métricas de aprendizado, tentativas e progresso da turma.
Quick Start
Ubuntu / WSL / Codespaces
curl -fsSL https://raw.githubusercontent.com/senapk/tko/main/install.sh | bash
tko --version
tko --help
Saída esperada:
- O comando
tko --versiondeve mostrar a versão instalada. - O comando
tko --helpdeve listar os comandos principais (task,repo,config,run, ...).
No repositório Git do aluno, tko git sync confirma e salva alterações locais,
recebe atualizações de origin/main e envia os commits. Em caso de conflito,
resolva os arquivos indicados e execute o comando novamente.
Para substituir cópias locais pelo remoto, tko git reset-to-remote descarta
alterações e commits locais e apaga arquivos não rastreados e ignorados.
Se tko não for encontrado, adicione ~/.local/bin ao PATH e abra um novo terminal:
export PATH="$HOME/.local/bin:$PATH"
Instalações existentes via pipx continuam suportadas:
pipx install tko
Windows
Use o guia recomendado para setup com VS Code, WSL e Ubuntu:
Comandos principais
tko
├── open, review, run, update, uninstall
├── task show, open, down, check
├── repo init, list, migrate, profile, source, audit
├── build task, index, download
├── tests convert, list, update-outputs
├── git sync, reset-to-remote
├── collect repo, tasks, skills
├── config set, list, reset [cache|settings|languages]
└── tool timeline, unpack, mdpp, older, diff, rebase, filter, html
# No repositório do aluno
tko task down course@labs/fila
tko task show course/labs/fila
tko task open course/labs/fila
# Dentro da pasta da atividade, o caminho é implícito
tko task show
tko run --language py --side
# Escolher outra atividade explicitamente
tko task open --fzf
# Diretório efetivo para qualquer comando
tko -C caminho/do/repositorio repo migrate --dry-run
tko -C caminho/do/repositorio repo migrate
task show e task open aceitam caminhos existentes. Sem caminho, usam a
atividade da pasta atual ou abrem um seletor quando não há atividade atual.
task down recebe uma chave, pois a atividade ainda não foi baixada.
--fzf/-f abre o seletor; --filter/-F filtra código antes da execução.
O idioma da interface usa --ui-language pt|en antes do comando; a linguagem de
programação usa --language/-l em init, run e collect skills.
Veja a referência da CLI para parâmetros e exemplos completos.
Para revisar uma pasta com um repositório TKO por aluno, use tko review PASTA.
Na interface, n e N alternam entre alunos, mantendo a tarefa selecionada,
as quests expandidas e o painel. Com uma tarefa selecionada, m abre a tabela
da turma para comparar avaliação, execuções, versões, tempo e último evento de
todos os alunos; Enter abre o aluno destacado e e exporta um CSV. As ações
normais do TKO continuam disponíveis;
o comando não executa reset-to-remote automaticamente. Repositórios que
precisem de migração são migrados ao serem abertos na revisão.
Casos de Uso
- Distribuição de listas e atividades de programação via Git.
- Desenvolvimento local na IDE do aluno, sem dependência de browser.
- Correção automática com testes e iteração rápida.
- Acompanhamento docente com indicadores de progresso e histórico.
Documentação por Perfil
- Conceitos e arquitetura: TKO: conceitos e organização
- Professor da disciplina (distribui conteúdo e coleta repositórios dos alunos via Git/GitHub): Uso pelos professores, Guia para criar repositórios de tarefas
- Aluno da disciplina: Uso do TKO pelos alunos, Fazendo as atividades
- Aluno em estudo autônomo (fora de disciplina): Testando sem estar em uma disciplina, Repositórios de referência
- Instalação e ambiente: Instalação
- Desenvolvedores: Uso pelos desenvolvedores
- Ferramentas auxiliares: Ferramentas
Repositórios de referência:
Instalação
- Guia recomendado: Windows com WSL e Ubuntu
- Ubuntu / WSL: Git, Python e TKO
- GitHub Codespaces
- VS Code no Ubuntu / WSL
- Linguagens - Java, C, C++, Python, TypeScript, Go
- Outros sistemas operacionais
- Windows sem WSL - legado
Uso do TKO pelos alunos
- Testando sem estar em uma disciplina
- Como organizar seus repositórios da disciplina
- Fazendo as atividades
Uso pelos professores
- Conceitos e organização do TKO
- Gestão de repositórios de turma
- Guia para criar repositórios de tarefas
- Marcadores e tipos de atividades
- Criando testes e conversões
- Gamificação e progressão
- Relizando provas com modo auditoria
- Analisando a timeline de execução de uma tarefa
Uso pelos desenvolvedores
Ferramentas
- Filtragem e Rascunhos
- Markdown Preprocessor
- Rebase de links markdown
- Build task: pipeline de mdpp, filter e drafts
- Build index: manter e atualizar índices
Referência e suporte
- Índice da documentação
- Guia de contribuição
- Arquitetura técnica
- FAQ
- Referência rápida da CLI
- Especificação de formatos
- Exemplos end-to-end
- Ciclo de vida de tarefas
- Suporte a linguagens
- Guia de testes e QA
Atualizando o TKO
Para a instalação recomendada, use:
tko update
Para instalações existentes via pipx, use:
pipx upgrade tko
Contribuição
Contribuições são bem-vindas via pull request.
Fluxo mínimo para validar mudanças localmente:
uv run pytest -q
Se possível, mantenha mudanças pequenas, com descrição clara do problema e da solução no PR.
Licença
Este projeto está sob a licença MIT. Veja LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for tko 12.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tko-12.5.0.tar.gz | 284.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tko-12.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 648.8 kB
Release files / tko-12.5.0.tar.gz
| Download URL | tko-12.5.0.tar.gz |
|---|---|
| Size | 284.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8d6b5eeb794c8a8237f0f020d1ce7aa93e0199fdce13720c4e3b43bde2b0e577
|
|
BLAKE2b-256 checksum How to use checksums |
f72074d5622bf981955e96f813b388920d4e334567421de3225548fba9882c2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tko-12.5.0-py3-none-any.whl
| Download URL | tko-12.5.0-py3-none-any.whl |
|---|---|
| Size | 364.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
970ee3a8bffc7794a34e8575a6445dcb9e03ba6bad22458854e9199c32c312cb
|
|
BLAKE2b-256 checksum How to use checksums |
71ce7bd9b2c4f66631526311db963e54ac7b4ff042b5d266d32ce378e9b526b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
